fs_selfservice/FS-SelfService/SelfService.pm

   1 package FS::SelfService;
   2
   3 use strict;
   4 use vars qw( $VERSION @ISA @EXPORT_OK $DEBUG
   5              $skip_uid_check $dir $socket %autoload $tag );
   6 use Exporter;
   7 use Socket;
   8 use FileHandle;
   9 #use IO::Handle;
  10 use IO::Select;
  11 use Storable 2.09 qw(nstore_fd fd_retrieve);
  12
  13 $VERSION = '0.03';
  14
  15 @ISA = qw( Exporter );
  16
  17 $DEBUG = 0;
  18
  19 $dir = "/usr/local/freeside";
  20 $socket =  "$dir/selfservice_socket";
  21 $socket .= '.'.$tag if defined $tag && length($tag);
  22
  23 #maybe should ask ClientAPI for this list
  24 %autoload = (
  25   'passwd'                    => 'passwd/passwd',
  26   'chfn'                      => 'passwd/passwd',
  27   'chsh'                      => 'passwd/passwd',
  28   'login_info'                => 'MyAccount/login_info',
  29   'login'                     => 'MyAccount/login',
  30   'logout'                    => 'MyAccount/logout',
  31   'customer_info'             => 'MyAccount/customer_info',
  32   'edit_info'                 => 'MyAccount/edit_info',     #add to ss cgi!
  33   'invoice'                   => 'MyAccount/invoice',
  34   'invoice_logo'              => 'MyAccount/invoice_logo',
  35   'list_invoices'             => 'MyAccount/list_invoices', #?
  36   'cancel'                    => 'MyAccount/cancel',        #add to ss cgi!
  37   'payment_info'              => 'MyAccount/payment_info',
  38   'payment_info_renew_info'   => 'MyAccount/payment_info_renew_info',
  39   'process_payment'           => 'MyAccount/process_payment',
  40   'process_payment_order_pkg' => 'MyAccount/process_payment_order_pkg',
  41   'process_payment_change_pkg' => 'MyAccount/process_payment_change_pkg',
  42   'process_payment_order_renew' => 'MyAccount/process_payment_order_renew',
  43   'process_prepay'            => 'MyAccount/process_prepay',
  44   'realtime_collect'          => 'MyAccount/realtime_collect',
  45   'list_pkgs'                 => 'MyAccount/list_pkgs',     #add to ss (added?)
  46   'list_svcs'                 => 'MyAccount/list_svcs',     #add to ss (added?)
  47   'list_svc_usage'            => 'MyAccount/list_svc_usage',
  48   'list_cdr_usage'            => 'MyAccount/list_cdr_usage',
  49   'list_support_usage'        => 'MyAccount/list_support_usage',
  50   'order_pkg'                 => 'MyAccount/order_pkg',     #add to ss cgi!
  51   'change_pkg'                => 'MyAccount/change_pkg',
  52   'order_recharge'            => 'MyAccount/order_recharge',
  53   'renew_info'                => 'MyAccount/renew_info',
  54   'order_renew'               => 'MyAccount/order_renew',
  55   'cancel_pkg'                => 'MyAccount/cancel_pkg',    #add to ss cgi!
  56   'charge'                    => 'MyAccount/charge',        #?
  57   'part_svc_info'             => 'MyAccount/part_svc_info',
  58   'provision_acct'            => 'MyAccount/provision_acct',
  59   'provision_external'        => 'MyAccount/provision_external',
  60   'unprovision_svc'           => 'MyAccount/unprovision_svc',
  61   'myaccount_passwd'          => 'MyAccount/myaccount_passwd',
  62   'signup_info'               => 'Signup/signup_info',
  63   'domain_select_hash'        => 'Signup/domain_select_hash',  # expose?
  64   'new_customer'              => 'Signup/new_customer',
  65   'capture_payment'           => 'Signup/capture_payment',
  66   'agent_login'               => 'Agent/agent_login',
  67   'agent_logout'              => 'Agent/agent_logout',
  68   'agent_info'                => 'Agent/agent_info',
  69   'agent_list_customers'      => 'Agent/agent_list_customers',
  70   'mason_comp'                => 'MasonComponent/mason_comp',
  71   'call_time'                 => 'PrepaidPhone/call_time',
  72   'call_time_nanpa'           => 'PrepaidPhone/call_time_nanpa',
  73   'phonenum_balance'          => 'PrepaidPhone/phonenum_balance',
  74   #sg
  75   'decompify_pkgs'            => 'SGNG/decompify_pkgs',
  76   'previous_payment_info'     => 'SGNG/previous_payment_info',
  77   'previous_payment_info_renew_info'
  78                               => 'SGNG/previous_payment_info_renew_info',
  79   'previous_process_payment'  => 'SGNG/previous_process_payment',
  80   'previous_process_payment_order_pkg'
  81                               => 'SGNG/previous_process_payment_order_pkg',
  82   'previous_process_payment_change_pkg'
  83                               => 'SGNG/previous_process_payment_change_pkg',
  84   'previous_process_payment_order_renew'
  85                               => 'SGNG/previous_process_payment_order_renew',
  86 );
  87 @EXPORT_OK = (
  88   keys(%autoload),
  89   qw( regionselector regionselector_hashref
  90       expselect popselector domainselector didselector )
  91 );
  92
  93 $ENV{'PATH'} ='/usr/bin:/usr/ucb:/bin';
  94 $ENV{'SHELL'} = '/bin/sh';
  95 $ENV{'IFS'} = " \t\n";
  96 $ENV{'CDPATH'} = '';
  97 $ENV{'ENV'} = '';
  98 $ENV{'BASH_ENV'} = '';
  99
 100 #you can add BEGIN { $FS::SelfService::skip_uid_check = 1; }
 101 #if you grant appropriate permissions to whatever user
 102 my $freeside_uid = scalar(getpwnam('freeside'));
 103 die "not running as the freeside user\n"
 104   if $> != $freeside_uid && ! $skip_uid_check;
 105
 106 -e $dir or die "FATAL: $dir doesn't exist!";
 107 -d $dir or die "FATAL: $dir isn't a directory!";
 108 -r $dir or die "FATAL: Can't read $dir as freeside user!";
 109 -x $dir or die "FATAL: $dir not searchable (executable) as freeside user!";
 110
 111 foreach my $autoload ( keys %autoload ) {
 112
 113   my $eval =
 114   "sub $autoload { ". '
 115                    my $param;
 116                    if ( ref($_[0]) ) {
 117                      $param = shift;
 118                    } else {
 119                      #warn scalar(@_). ": ". join(" / ", @_);
 120                      $param = { @_ };
 121                    }
 122
 123                    $param->{_packet} = \''. $autoload{$autoload}. '\';
 124
 125                    simple_packet($param);
 126                  }';
 127
 128   eval $eval;
 129   die $@ if $@;
 130
 131 }
 132
 133 sub simple_packet {
 134   my $packet = shift;
 135   warn "sending ". $packet->{_packet}. " to server"
 136     if $DEBUG;
 137   socket(SOCK, PF_UNIX, SOCK_STREAM, 0) or die "socket: $!";
 138   connect(SOCK, sockaddr_un($socket)) or die "connect to $socket: $!";
 139   nstore_fd($packet, \*SOCK) or die "can't send packet: $!";
 140   SOCK->flush;
 141
 142   #shoudl trap: Magic number checking on storable file failed at blib/lib/Storable.pm (autosplit into blib/lib/auto/Storable/fd_retrieve.al) line 337, at /usr/local/share/perl/5.6.1/FS/SelfService.pm line 71
 143
 144   #block until there is a message on socket
 145 #  my $w = new IO::Select;
 146 #  $w->add(\*SOCK);
 147 #  my @wait = $w->can_read;
 148
 149   warn "reading message from server"
 150     if $DEBUG;
 151
 152   my $return = fd_retrieve(\*SOCK) or die "error reading result: $!";
 153   die $return->{'_error'} if defined $return->{_error} && $return->{_error};
 154
 155   warn "returning message to client"
 156     if $DEBUG;
 157
 158   $return;
 159 }
 160
 161 =head1 NAME
 162
 163 FS::SelfService - Freeside self-service API
 164
 165 =head1 SYNOPSIS
 166
 167   # password and shell account changes
 168   use FS::SelfService qw(passwd chfn chsh);
 169
 170   # "my account" functionality
 171   use FS::SelfService qw( login customer_info invoice cancel payment_info process_payment );
 172
 173   my $rv = login( { 'username' => $username,
 174                     'domain'   => $domain,
 175                     'password' => $password,
 176                   }
 177                 );
 178
 179   if ( $rv->{'error'} ) {
 180     #handle login error...
 181   } else {
 182     #successful login
 183     my $session_id = $rv->{'session_id'};
 184   }
 185
 186   my $customer_info = customer_info( { 'session_id' => $session_id } );
 187
 188   #payment_info and process_payment are available in 1.5+ only
 189   my $payment_info = payment_info( { 'session_id' => $session_id } );
 190
 191   #!!! process_payment example
 192
 193   #!!! list_pkgs example
 194
 195   #!!! order_pkg example
 196
 197   #!!! cancel_pkg example
 198
 199   # signup functionality
 200   use FS::SelfService qw( signup_info new_customer );
 201
 202   my $signup_info = signup_info;
 203
 204   $rv = new_customer( {
 205                         'first'            => $first,
 206                         'last'             => $last,
 207                         'company'          => $company,
 208                         'address1'         => $address1,
 209                         'address2'         => $address2,
 210                         'city'             => $city,
 211                         'state'            => $state,
 212                         'zip'              => $zip,
 213                         'country'          => $country,
 214                         'daytime'          => $daytime,
 215                         'night'            => $night,
 216                         'fax'              => $fax,
 217                         'payby'            => $payby,
 218                         'payinfo'          => $payinfo,
 219                         'paycvv'           => $paycvv,
 220                         'paystart_month'   => $paystart_month
 221                         'paystart_year'    => $paystart_year,
 222                         'payissue'         => $payissue,
 223                         'payip'            => $payip
 224                         'paydate'          => $paydate,
 225                         'payname'          => $payname,
 226                         'invoicing_list'   => $invoicing_list,
 227                         'referral_custnum' => $referral_custnum,
 228                         'agentnum'         => $agentnum,
 229                         'pkgpart'          => $pkgpart,
 230
 231                         'username'         => $username,
 232                         '_password'        => $password,
 233                         'popnum'           => $popnum,
 234                         #OR
 235                         'countrycode'      => 1,
 236                         'phonenum'         => $phonenum,
 237                         'pin'              => $pin,
 238                       }
 239                     );
 240
 241   my $error = $rv->{'error'};
 242   if ( $error eq '_decline' ) {
 243     print_decline();
 244   } elsif ( $error ) {
 245     reprint_signup();
 246   } else {
 247     print_success();
 248   }
 249
 250 =head1 DESCRIPTION
 251
 252 Use this API to implement your own client "self-service" module.
 253
 254 If you just want to customize the look of the existing "self-service" module,
 255 see XXXX instead.
 256
 257 =head1 PASSWORD, GECOS, SHELL CHANGING FUNCTIONS
 258
 259 =over 4
 260
 261 =item passwd
 262
 263 =item chfn
 264
 265 =item chsh
 266
 267 =back
 268
 269 =head1 "MY ACCOUNT" FUNCTIONS
 270
 271 =over 4
 272
 273 =item login HASHREF
 274
 275 Creates a user session.  Takes a hash reference as parameter with the
 276 following keys:
 277
 278 =over 4
 279
 280 =item username
 281
 282 Username
 283
 284 =item domain
 285
 286 Domain
 287
 288 =item password
 289
 290 Password
 291
 292 =back
 293
 294 Returns a hash reference with the following keys:
 295
 296 =over 4
 297
 298 =item error
 299
 300 Empty on success, or an error message on errors.
 301
 302 =item session_id
 303
 304 Session identifier for successful logins
 305
 306 =back
 307
 308 =item customer_info HASHREF
 309
 310 Returns general customer information.
 311
 312 Takes a hash reference as parameter with a single key: B<session_id>
 313
 314 Returns a hash reference with the following keys:
 315
 316 =over 4
 317
 318 =item name
 319
 320 Customer name
 321
 322 =item balance
 323
 324 Balance owed
 325
 326 =item open
 327
 328 Array reference of hash references of open inoices.  Each hash reference has
 329 the following keys: invnum, date, owed
 330
 331 =item small_custview
 332
 333 An HTML fragment containing shipping and billing addresses.
 334
 335 =item The following fields are also returned
 336
 337 first last company address1 address2 city county state zip country daytime night fax ship_first ship_last ship_company ship_address1 ship_address2 ship_city ship_state ship_zip ship_country ship_daytime ship_night ship_fax payby payinfo payname month year invoicing_list postal_invoicing
 338
 339 =back
 340
 341 =item edit_info HASHREF
 342
 343 Takes a hash reference as parameter with any of the following keys:
 344
 345 first last company address1 address2 city county state zip country daytime night fax ship_first ship_last ship_company ship_address1 ship_address2 ship_city ship_state ship_zip ship_country ship_daytime ship_night ship_fax payby payinfo paycvv payname month year invoicing_list postal_invoicing
 346
 347 If a field exists, the customer record is updated with the new value of that
 348 field.  If a field does not exist, that field is not changed on the customer
 349 record.
 350
 351 Returns a hash reference with a single key, B<error>, empty on success, or an
 352 error message on errors
 353
 354 =item invoice HASHREF
 355
 356 Returns an invoice.  Takes a hash reference as parameter with two keys:
 357 session_id and invnum
 358
 359 Returns a hash reference with the following keys:
 360
 361 =over 4
 362
 363 =item error
 364
 365 Empty on success, or an error message on errors
 366
 367 =item invnum
 368
 369 Invoice number
 370
 371 =item invoice_text
 372
 373 Invoice text
 374
 375 =back
 376
 377 =item list_invoices HASHREF
 378
 379 Returns a list of all customer invoices.  Takes a hash references with a single
 380 key, session_id.
 381
 382 Returns a hash reference with the following keys:
 383
 384 =over 4
 385
 386 =item error
 387
 388 Empty on success, or an error message on errors
 389
 390 =item invoices
 391
 392 Reference to array of hash references with the following keys:
 393
 394 =over 4
 395
 396 =item invnum
 397
 398 Invoice ID
 399
 400 =item _date
 401
 402 Invoice date, in UNIX epoch time
 403
 404 =back
 405
 406 =back
 407
 408 =item cancel HASHREF
 409
 410 Cancels this customer.
 411
 412 Takes a hash reference as parameter with a single key: B<session_id>
 413
 414 Returns a hash reference with a single key, B<error>, which is empty on
 415 success or an error message on errors.
 416
 417 =item payment_info HASHREF
 418
 419 Returns information that may be useful in displaying a payment page.
 420
 421 Takes a hash reference as parameter with a single key: B<session_id>.
 422
 423 Returns a hash reference with the following keys:
 424
 425 =over 4
 426
 427 =item error
 428
 429 Empty on success, or an error message on errors
 430
 431 =item balance
 432
 433 Balance owed
 434
 435 =item payname
 436
 437 Exact name on credit card (CARD/DCRD)
 438
 439 =item address1
 440
 441 Address line one
 442
 443 =item address2
 444
 445 Address line two
 446
 447 =item city
 448
 449 City
 450
 451 =item state
 452
 453 State
 454
 455 =item zip
 456
 457 Zip or postal code
 458
 459 =item payby
 460
 461 Customer's current default payment type.
 462
 463 =item card_type
 464
 465 For CARD/DCRD payment types, the card type (Visa card, MasterCard, Discover card, American Express card, etc.)
 466
 467 =item payinfo
 468
 469 For CARD/DCRD payment types, the card number
 470
 471 =item month
 472
 473 For CARD/DCRD payment types, expiration month
 474
 475 =item year
 476
 477 For CARD/DCRD payment types, expiration year
 478
 479 =item cust_main_county
 480
 481 County/state/country data - array reference of hash references, each of which has the fields of a cust_main_county record (see L<FS::cust_main_county>).  Note these are not FS::cust_main_county objects, but hash references of columns and values.
 482
 483 =item states
 484
 485 Array reference of all states in the current default country.
 486
 487 =item card_types
 488
 489 Hash reference of card types; keys are card types, values are the exact strings
 490 passed to the process_payment function
 491
 492 =cut
 493
 494 #this doesn't actually work yet
 495 #
 496 #=item paybatch
 497 #
 498 #Unique transaction identifier (prevents multiple charges), passed to the
 499 #process_payment function
 500
 501 =back
 502
 503 =item process_payment HASHREF
 504
 505 Processes a payment and possible change of address or payment type.  Takes a
 506 hash reference as parameter with the following keys:
 507
 508 =over 4
 509
 510 =item session_id
 511
 512 Session identifier
 513
 514 =item amount
 515
 516 Amount
 517
 518 =item save
 519
 520 If true, address and card information entered will be saved for subsequent
 521 transactions.
 522
 523 =item auto
 524
 525 If true, future credit card payments will be done automatically (sets payby to
 526 CARD).  If false, future credit card payments will be done on-demand (sets
 527 payby to DCRD).  This option only has meaning if B<save> is set true.
 528
 529 =item payname
 530
 531 Name on card
 532
 533 =item address1
 534
 535 Address line one
 536
 537 =item address2
 538
 539 Address line two
 540
 541 =item city
 542
 543 City
 544
 545 =item state
 546
 547 State
 548
 549 =item zip
 550
 551 Zip or postal code
 552
 553 =item payinfo
 554
 555 Card number
 556
 557 =item month
 558
 559 Card expiration month
 560
 561 =item year
 562
 563 Card expiration year
 564
 565 =cut
 566
 567 #this doesn't actually work yet
 568 #
 569 #=item paybatch
 570 #
 571 #Unique transaction identifier, returned from the payment_info function.
 572 #Prevents multiple charges.
 573
 574 =back
 575
 576 Returns a hash reference with a single key, B<error>, empty on success, or an
 577 error message on errors.
 578
 579 =item process_payment_order_pkg
 580
 581 Combines the B<process_payment> and B<order_pkg> functions in one step.  If the
 582 payment processes sucessfully, the package is ordered.  Takes a hash reference
 583 as parameter with the keys of both methods.
 584
 585 Returns a hash reference with a single key, B<error>, empty on success, or an
 586 error message on errors.
 587
 588 =item process_payment_change_pkg
 589
 590 Combines the B<process_payment> and B<change_pkg> functions in one step.  If the
 591 payment processes sucessfully, the package is ordered.  Takes a hash reference
 592 as parameter with the keys of both methods.
 593
 594 Returns a hash reference with a single key, B<error>, empty on success, or an
 595 error message on errors.
 596
 597
 598 =item process_payment_order_renew
 599
 600 Combines the B<process_payment> and B<order_renew> functions in one step.  If
 601 the payment processes sucessfully, the renewal is processed.  Takes a hash
 602 reference as parameter with the keys of both methods.
 603
 604 Returns a hash reference with a single key, B<error>, empty on success, or an
 605 error message on errors.
 606
 607 =item list_pkgs
 608
 609 Returns package information for this customer.  For more detail on services,
 610 see L</list_svcs>.
 611
 612 Takes a hash reference as parameter with a single key: B<session_id>
 613
 614 Returns a hash reference containing customer package information.  The hash reference contains the following keys:
 615
 616 =over 4
 617
 618 =item custnum
 619
 620 Customer number
 621
 622 =item error
 623
 624 Empty on success, or an error message on errors.
 625
 626 =item cust_pkg HASHREF
 627
 628 Array reference of hash references, each of which has the fields of a cust_pkg
 629 record (see L<FS::cust_pkg>) as well as the fields below.  Note these are not
 630 the internal FS:: objects, but hash references of columns and values.
 631
 632 =over 4
 633
 634 =item part_pkg fields
 635
 636 All fields of part_pkg for this specific cust_pkg (be careful with this
 637 information - it may reveal more about your available packages than you would
 638 like users to know in aggregate)
 639
 640 =cut
 641
 642 #XXX pare part_pkg fields down to a more secure subset
 643
 644 =item part_svc
 645
 646 An array of hash references indicating information on unprovisioned services
 647 available for provisioning for this specific cust_pkg.  Each has the following
 648 keys:
 649
 650 =over 4
 651
 652 =item part_svc fields
 653
 654 All fields of part_svc (be careful with this information - it may reveal more
 655 about your available packages than you would like users to know in aggregate)
 656
 657 =cut
 658
 659 #XXX pare part_svc fields down to a more secure subset
 660
 661 =back
 662
 663 =item cust_svc
 664
 665 An array of hash references indicating information on the customer services
 666 already provisioned for this specific cust_pkg.  Each has the following keys:
 667
 668 =over 4
 669
 670 =item label
 671
 672 Array reference with three elements: The first element is the name of this service.  The second element is a meaningful user-specific identifier for the service (i.e. username, domain or mail alias).  The last element is the table name of this service.
 673
 674 =back
 675
 676 =item svcnum
 677
 678 Primary key for this service
 679
 680 =item svcpart
 681
 682 Service definition (see L<FS::part_svc>)
 683
 684 =item pkgnum
 685
 686 Customer package (see L<FS::cust_pkg>)
 687
 688 =item overlimit
 689
 690 Blank if the service is not over limit, or the date the service exceeded its usage limit (as a UNIX timestamp).
 691
 692 =back
 693
 694 =back
 695
 696 =item list_svcs
 697
 698 Returns service information for this customer.
 699
 700 Takes a hash reference as parameter with a single key: B<session_id>
 701
 702 Returns a hash reference containing customer package information.  The hash reference contains the following keys:
 703
 704 =over 4
 705
 706 =item custnum
 707
 708 Customer number
 709
 710 =item svcs
 711
 712 An array of hash references indicating information on all of this customer's
 713 services.  Each has the following keys:
 714
 715 =over 4
 716
 717 =item svcnum
 718
 719 Primary key for this service
 720
 721 =item label
 722
 723 Name of this service
 724
 725 =item value
 726
 727 Meaningful user-specific identifier for the service (i.e. username, domain, or
 728 mail alias).
 729
 730 =back
 731
 732 Account (svc_acct) services also have the following keys:
 733
 734 =over 4
 735
 736 =item username
 737
 738 Username
 739
 740 =item email
 741
 742 username@domain
 743
 744 =item seconds
 745
 746 Seconds remaining
 747
 748 =item upbytes
 749
 750 Upload bytes remaining
 751
 752 =item downbytes
 753
 754 Download bytes remaining
 755
 756 =item totalbytes
 757
 758 Total bytes remaining
 759
 760 =item recharge_amount
 761
 762 Cost of a recharge
 763
 764 =item recharge_seconds
 765
 766 Number of seconds gained by recharge
 767
 768 =item recharge_upbytes
 769
 770 Number of upload bytes gained by recharge
 771
 772 =item recharge_downbytes
 773
 774 Number of download bytes gained by recharge
 775
 776 =item recharge_totalbytes
 777
 778 Number of total bytes gained by recharge
 779
 780 =back
 781
 782 =back
 783
 784 =item order_pkg
 785
 786 Orders a package for this customer.
 787
 788 Takes a hash reference as parameter with the following keys:
 789
 790 =over 4
 791
 792 =item session_id
 793
 794 Session identifier
 795
 796 =item pkgpart
 797
 798 Package to order (see L<FS::part_pkg>).
 799
 800 =item svcpart
 801
 802 Service to order (see L<FS::part_svc>).
 803
 804 Normally optional; required only to provision a non-svc_acct service, or if the
 805 package definition does not contain one svc_acct service definition with
 806 quantity 1 (it may contain others with quantity >1).  A svcpart of "none" can
 807 also be specified to indicate that no initial service should be provisioned.
 808
 809 =back
 810
 811 Fields used when provisioning an svc_acct service:
 812
 813 =over 4
 814
 815 =item username
 816
 817 Username
 818
 819 =item _password
 820
 821 Password
 822
 823 =item sec_phrase
 824
 825 Optional security phrase
 826
 827 =item popnum
 828
 829 Optional Access number number
 830
 831 =back
 832
 833 Fields used when provisioning an svc_domain service:
 834
 835 =over 4
 836
 837 =item domain
 838
 839 Domain
 840
 841 =back
 842
 843 Fields used when provisioning an svc_phone service:
 844
 845 =over 4
 846
 847 =item phonenum
 848
 849 Phone number
 850
 851 =item pin
 852
 853 Voicemail PIN
 854
 855 =item sip_password
 856
 857 SIP password
 858
 859 =back
 860
 861 Fields used when provisioning an svc_external service:
 862
 863 =over 4
 864
 865 =item id
 866
 867 External numeric ID.
 868
 869 =item title
 870
 871 External text title.
 872
 873 =back
 874
 875 Returns a hash reference with a single key, B<error>, empty on success, or an
 876 error message on errors.  The special error '_decline' is returned for
 877 declined transactions.
 878
 879 =item change_pkg
 880
 881 Changes a package for this customer.
 882
 883 Takes a hash reference as parameter with the following keys:
 884
 885 =over 4
 886
 887 =item session_id
 888
 889 Session identifier
 890
 891 =item pkgnum
 892
 893 Existing customer package.
 894
 895 =item pkgpart
 896
 897 New package to order (see L<FS::part_pkg>).
 898
 899 =back
 900
 901 Returns a hash reference with a single key, B<error>, empty on success, or an
 902 error message on errors.
 903
 904 =item renew_info
 905
 906 Provides useful info for early renewals.
 907
 908 Takes a hash reference as parameter with the following keys:
 909
 910 =over 4
 911
 912 =item session_id
 913
 914 Session identifier
 915
 916 =back
 917
 918 Returns a hash reference.  On errors, it contains a single key, B<error>, with
 919 the error message.  Otherwise, contains a single key, B<dates>, pointing to
 920 an array refernce of hash references.  Each hash reference contains the
 921 following keys:
 922
 923 =over 4
 924
 925 =item bill_date
 926
 927 (Future) Bill date.  Indicates a future date for which billing could be run.
 928 Specified as a integer UNIX timestamp.  Pass this value to the B<order_renew>
 929 function.
 930
 931 =item bill_date_pretty
 932
 933 (Future) Bill date as a human-readable string.  (Convenience for display;
 934 subject to change, so best not to parse for the date.)
 935
 936 =item amount
 937
 938 Base amount which will be charged if renewed early as of this date.
 939
 940 =item renew_date
 941
 942 Renewal date; i.e. even-futher future date at which the customer will be paid
 943 through if the early renewal is completed with the given B<bill-date>.
 944 Specified as a integer UNIX timestamp.
 945
 946 =item renew_date_pretty
 947
 948 Renewal date as a human-readable string.  (Convenience for display;
 949 subject to change, so best not to parse for the date.)
 950
 951 =item pkgnum
 952
 953 Package that will be renewed.
 954
 955 =item expire_date
 956
 957 Expiration date of the package that will be renewed.
 958
 959 =item expire_date_pretty
 960
 961 Expiration date of the package that will be renewed, as a human-readable
 962 string.  (Convenience for display; subject to change, so best not to parse for
 963 the date.)
 964
 965 =back
 966
 967 =item order_renew
 968
 969 Renews this customer early; i.e. runs billing for this customer in advance.
 970
 971 Takes a hash reference as parameter with the following keys:
 972
 973 =over 4
 974
 975 =item session_id
 976
 977 Session identifier
 978
 979 =item date
 980
 981 Integer date as returned by the B<renew_info> function, indicating the advance
 982 date for which to run billing.
 983
 984 =back
 985
 986 Returns a hash reference with a single key, B<error>, empty on success, or an
 987 error message on errors.
 988
 989 =item cancel_pkg
 990
 991 Cancels a package for this customer.
 992
 993 Takes a hash reference as parameter with the following keys:
 994
 995 =over 4
 996
 997 =item session_id
 998
 999 Session identifier
1000
1001 =item pkgpart
1002
1003 pkgpart of package to cancel
1004
1005 =back
1006
1007 Returns a hash reference with a single key, B<error>, empty on success, or an
1008 error message on errors.
1009
1010 =back
1011
1012 =head1 SIGNUP FUNCTIONS
1013
1014 =over 4
1015
1016 =item signup_info HASHREF
1017
1018 Takes a hash reference as parameter with the following keys:
1019
1020 =over 4
1021
1022 =item session_id - Optional agent/reseller interface session
1023
1024 =back
1025
1026 Returns a hash reference containing information that may be useful in
1027 displaying a signup page.  The hash reference contains the following keys:
1028
1029 =over 4
1030
1031 =item cust_main_county
1032
1033 County/state/country data - array reference of hash references, each of which has the fields of a cust_main_county record (see L<FS::cust_main_county>).  Note these are not FS::cust_main_county objects, but hash references of columns and values.
1034
1035 =item part_pkg
1036
1037 Available packages - array reference of hash references, each of which has the fields of a part_pkg record (see L<FS::part_pkg>).  Each hash reference also has an additional 'payby' field containing an array reference of acceptable payment types specific to this package (see below and L<FS::part_pkg/payby>).  Note these are not FS::part_pkg objects, but hash references of columns and values.  Requires the 'signup_server-default_agentnum' configuration value to be set, or
1038 an agentnum specified explicitly via reseller interface session_id in the
1039 options.
1040
1041 =item agent
1042
1043 Array reference of hash references, each of which has the fields of an agent record (see L<FS::agent>).  Note these are not FS::agent objects, but hash references of columns and values.
1044
1045 =item agentnum2part_pkg
1046
1047 Hash reference; keys are agentnums, values are array references of available packages for that agent, in the same format as the part_pkg arrayref above.
1048
1049 =item svc_acct_pop
1050
1051 Access numbers - array reference of hash references, each of which has the fields of an svc_acct_pop record (see L<FS::svc_acct_pop>).  Note these are not FS::svc_acct_pop objects, but hash references of columns and values.
1052
1053 =item security_phrase
1054
1055 True if the "security_phrase" feature is enabled
1056
1057 =item payby
1058
1059 Array reference of acceptable payment types for signup
1060
1061 =over 4
1062
1063 =item CARD
1064
1065 credit card - automatic
1066
1067 =item DCRD
1068
1069 credit card - on-demand - version 1.5+ only
1070
1071 =item CHEK
1072
1073 electronic check - automatic
1074
1075 =item DCHK
1076
1077 electronic check - on-demand - version 1.5+ only
1078
1079 =item LECB
1080
1081 Phone bill billing
1082
1083 =item BILL
1084
1085 billing, not recommended for signups
1086
1087 =item COMP
1088
1089 free, definitely not recommended for signups
1090
1091 =item PREPAY
1092
1093 special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL
1094
1095 =back
1096
1097 =item cvv_enabled
1098
1099 True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch)
1100
1101 =item msgcat
1102
1103 Hash reference of message catalog values, to support error message customization.  Currently available keys are: passwords_dont_match, invalid_card, unknown_card_type, and not_a (as in "Not a Discover card").  Values are configured in the web interface under "View/Edit message catalog".
1104
1105 =item statedefault
1106
1107 Default state
1108
1109 =item countrydefault
1110
1111 Default country
1112
1113 =back
1114
1115 =item new_customer HASHREF
1116
1117 Creates a new customer.  Takes a hash reference as parameter with the
1118 following keys:
1119
1120 =over 4
1121
1122 =item first
1123
1124 first name (required)
1125
1126 =item last
1127
1128 last name (required)
1129
1130 =item ss
1131
1132 (not typically collected; mostly used for ACH transactions)
1133
1134 =item company
1135
1136 Company name
1137
1138 =item address1 (required)
1139
1140 Address line one
1141
1142 =item address2
1143
1144 Address line two
1145
1146 =item city (required)
1147
1148 City
1149
1150 =item county
1151
1152 County
1153
1154 =item state (required)
1155
1156 State
1157
1158 =item zip (required)
1159
1160 Zip or postal code
1161
1162 =item daytime
1163
1164 Daytime phone number
1165
1166 =item night
1167
1168 Evening phone number
1169
1170 =item fax
1171
1172 Fax number
1173
1174 =item payby
1175
1176 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L</signup_info> (required)
1177
1178 =item payinfo
1179
1180 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
1181
1182 =item paycvv
1183
1184 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
1185
1186 =item paydate
1187
1188 Expiration date for CARD/DCRD
1189
1190 =item payname
1191
1192 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
1193
1194 =item invoicing_list
1195
1196 comma-separated list of email addresses for email invoices.  The special value 'POST' is used to designate postal invoicing (it may be specified alone or in addition to email addresses),
1197
1198 =item referral_custnum
1199
1200 referring customer number
1201
1202 =item agentnum
1203
1204 Agent number
1205
1206 =item pkgpart
1207
1208 pkgpart of initial package
1209
1210 =item username
1211
1212 Username
1213
1214 =item _password
1215
1216 Password
1217
1218 =item sec_phrase
1219
1220 Security phrase
1221
1222 =item popnum
1223
1224 Access number (index, not the literal number)
1225
1226 =item countrycode
1227
1228 Country code (to be provisioned as a service)
1229
1230 =item phonenum
1231
1232 Phone number (to be provisioned as a service)
1233
1234 =item pin
1235
1236 Voicemail PIN
1237
1238 =back
1239
1240 Returns a hash reference with the following keys:
1241
1242 =over 4
1243
1244 =item error
1245
1246 Empty on success, or an error message on errors.  The special error '_decline' is returned for declined transactions; other error messages should be suitable for display to the user (and are customizable in under Configuration | View/Edit message catalog)
1247
1248 =back
1249
1250 =item regionselector HASHREF | LIST
1251
1252 Takes as input a hashref or list of key/value pairs with the following keys:
1253
1254 =over 4
1255
1256 =item selected_county
1257
1258 Currently selected county
1259
1260 =item selected_state
1261
1262 Currently selected state
1263
1264 =item selected_country
1265
1266 Currently selected country
1267
1268 =item prefix
1269
1270 Specify a unique prefix string  if you intend to use the HTML output multiple time son one page.
1271
1272 =item onchange
1273
1274 Specify a javascript subroutine to call on changes
1275
1276 =item default_state
1277
1278 Default state
1279
1280 =item default_country
1281
1282 Default country
1283
1284 =item locales
1285
1286 An arrayref of hash references specifying regions.  Normally you can just pass the value of the I<cust_main_county> field returned by B<signup_info>.
1287
1288 =back
1289
1290 Returns a list consisting of three HTML fragments for county selection,
1291 state selection and country selection, respectively.
1292
1293 =cut
1294
1295 #false laziness w/FS::cust_main_county (this is currently the "newest" version)
1296 sub regionselector {
1297   my $param;
1298   if ( ref($_[0]) ) {
1299     $param = shift;
1300   } else {
1301     $param = { @_ };
1302   }
1303   $param->{'selected_country'} ||= $param->{'default_country'};
1304   $param->{'selected_state'} ||= $param->{'default_state'};
1305
1306   my $prefix = exists($param->{'prefix'}) ? $param->{'prefix'} : '';
1307
1308   my $countyflag = 0;
1309
1310   my %cust_main_county;
1311
1312 #  unless ( @cust_main_county ) { #cache
1313     #@cust_main_county = qsearch('cust_main_county', {} );
1314     #foreach my $c ( @cust_main_county ) {
1315     foreach my $c ( @{ $param->{'locales'} } ) {
1316       #$countyflag=1 if $c->county;
1317       $countyflag=1 if $c->{county};
1318       #push @{$cust_main_county{$c->country}{$c->state}}, $c->county;
1319       #$cust_main_county{$c->country}{$c->state}{$c->county} = 1;
1320       $cust_main_county{$c->{country}}{$c->{state}}{$c->{county}} = 1;
1321     }
1322 #  }
1323   $countyflag=1 if $param->{selected_county};
1324
1325   my $script_html = <<END;
1326     <SCRIPT>
1327     function opt(what,value,text) {
1328       var optionName = new Option(text, value, false, false);
1329       var length = what.length;
1330       what.options[length] = optionName;
1331     }
1332     function ${prefix}country_changed(what) {
1333       country = what.options[what.selectedIndex].text;
1334       for ( var i = what.form.${prefix}state.length; i >= 0; i-- )
1335           what.form.${prefix}state.options[i] = null;
1336 END
1337       #what.form.${prefix}state.options[0] = new Option('', '', false, true);
1338
1339   foreach my $country ( sort keys %cust_main_county ) {
1340     $script_html .= "\nif ( country == \"$country\" ) {\n";
1341     foreach my $state ( sort keys %{$cust_main_county{$country}} ) {
1342       my $text = $state || '(n/a)';
1343       $script_html .= qq!opt(what.form.${prefix}state, "$state", "$text");\n!;
1344     }
1345     $script_html .= "}\n";
1346   }
1347
1348   $script_html .= <<END;
1349     }
1350     function ${prefix}state_changed(what) {
1351 END
1352
1353   if ( $countyflag ) {
1354     $script_html .= <<END;
1355       state = what.options[what.selectedIndex].text;
1356       country = what.form.${prefix}country.options[what.form.${prefix}country.selectedIndex].text;
1357       for ( var i = what.form.${prefix}county.length; i >= 0; i-- )
1358           what.form.${prefix}county.options[i] = null;
1359 END
1360
1361     foreach my $country ( sort keys %cust_main_county ) {
1362       $script_html .= "\nif ( country == \"$country\" ) {\n";
1363       foreach my $state ( sort keys %{$cust_main_county{$country}} ) {
1364         $script_html .= "\nif ( state == \"$state\" ) {\n";
1365           #foreach my $county ( sort @{$cust_main_county{$country}{$state}} ) {
1366           foreach my $county ( sort keys %{$cust_main_county{$country}{$state}} ) {
1367             my $text = $county || '(n/a)';
1368             $script_html .=
1369               qq!opt(what.form.${prefix}county, "$county", "$text");\n!;
1370           }
1371         $script_html .= "}\n";
1372       }
1373       $script_html .= "}\n";
1374     }
1375   }
1376
1377   $script_html .= <<END;
1378     }
1379     </SCRIPT>
1380 END
1381
1382   my $county_html = $script_html;
1383   if ( $countyflag ) {
1384     $county_html .= qq!<SELECT NAME="${prefix}county" onChange="$param->{'onchange'}">!;
1385     $county_html .= '</SELECT>';
1386   } else {
1387     $county_html .=
1388       qq!<INPUT TYPE="hidden" NAME="${prefix}county" VALUE="$param->{'selected_county'}">!;
1389   }
1390
1391   my $state_html = qq!<SELECT NAME="${prefix}state" !.
1392                    qq!onChange="${prefix}state_changed(this); $param->{'onchange'}">!;
1393   foreach my $state ( sort keys %{ $cust_main_county{$param->{'selected_country'}} } ) {
1394     my $text = $state || '(n/a)';
1395     my $selected = $state eq $param->{'selected_state'} ? 'SELECTED' : '';
1396     $state_html .= "\n<OPTION $selected VALUE=$state>$text</OPTION>"
1397   }
1398   $state_html .= '</SELECT>';
1399
1400   my $country_html = '';
1401   if ( scalar( keys %cust_main_county ) > 1 )  {
1402
1403     $country_html = qq(<SELECT NAME="${prefix}country" ).
1404                     qq(onChange="${prefix}country_changed(this); ).
1405                                  $param->{'onchange'}.
1406                                '"'.
1407                       '>';
1408     my $countrydefault = $param->{default_country} || 'US';
1409     foreach my $country (
1410       sort { ($b eq $countrydefault) <=> ($a eq $countrydefault) or $a cmp $b }
1411         keys %cust_main_county
1412     ) {
1413       my $selected = $country eq $param->{'selected_country'}
1414                        ? ' SELECTED'
1415                        : '';
1416       $country_html .= "\n<OPTION$selected>$country</OPTION>"
1417     }
1418     $country_html .= '</SELECT>';
1419   } else {
1420
1421     $country_html = qq(<INPUT TYPE="hidden" NAME="${prefix}country" ).
1422                             ' VALUE="'. (keys %cust_main_county )[0]. '">';
1423
1424   }
1425
1426   ($county_html, $state_html, $country_html);
1427
1428 }
1429
1430 sub regionselector_hashref {
1431   my ($county_html, $state_html, $country_html) = regionselector(@_);
1432   {
1433     'county_html'  => $county_html,
1434     'state_html'   => $state_html,
1435     'country_html' => $country_html,
1436   };
1437 }
1438
1439 #=item expselect HASHREF | LIST
1440 #
1441 #Takes as input a hashref or list of key/value pairs with the following keys:
1442 #
1443 #=over 4
1444 #
1445 #=item prefix - Specify a unique prefix string  if you intend to use the HTML output multiple time son one page.
1446 #
1447 #=item date - current date, in yyyy-mm-dd or m-d-yyyy format
1448 #
1449 #=back
1450
1451 =item expselect PREFIX [ DATE ]
1452
1453 Takes as input a unique prefix string and the current expiration date, in
1454 yyyy-mm-dd or m-d-yyyy format
1455
1456 Returns an HTML fragments for expiration date selection.
1457
1458 =cut
1459
1460 sub expselect {
1461   #my $param;
1462   #if ( ref($_[0]) ) {
1463   #  $param = shift;
1464   #} else {
1465   #  $param = { @_ };
1466   #my $prefix = $param->{'prefix'};
1467   #my $prefix = exists($param->{'prefix'}) ? $param->{'prefix'} : '';
1468   #my $date =   exists($param->{'date'})   ? $param->{'date'}   : '';
1469   my $prefix = shift;
1470   my $date = scalar(@_) ? shift : '';
1471
1472   my( $m, $y ) = ( 0, 0 );
1473   if ( $date  =~ /^(\d{4})-(\d{2})-\d{2}$/ ) { #PostgreSQL date format
1474     ( $m, $y ) = ( $2, $1 );
1475   } elsif ( $date =~ /^(\d{1,2})-(\d{1,2}-)?(\d{4}$)/ ) {
1476     ( $m, $y ) = ( $1, $3 );
1477   }
1478   my $return = qq!<SELECT NAME="$prefix!. qq!_month" SIZE="1">!;
1479   for ( 1 .. 12 ) {
1480     $return .= qq!<OPTION VALUE="$_"!;
1481     $return .= " SELECTED" if $_ == $m;
1482     $return .= ">$_";
1483   }
1484   $return .= qq!</SELECT>/<SELECT NAME="$prefix!. qq!_year" SIZE="1">!;
1485   my @t = localtime;
1486   my $thisYear = $t[5] + 1900;
1487   for ( ($thisYear > $y && $y > 0 ? $y : $thisYear) .. ($thisYear+10) ) {
1488     $return .= qq!<OPTION VALUE="$_"!;
1489     $return .= " SELECTED" if $_ == $y;
1490     $return .= ">$_";
1491   }
1492   $return .= "</SELECT>";
1493
1494   $return;
1495 }
1496
1497 =item popselector HASHREF | LIST
1498
1499 Takes as input a hashref or list of key/value pairs with the following keys:
1500
1501 =over 4
1502
1503 =item popnum
1504
1505 Access number number
1506
1507 =item pops
1508
1509 An arrayref of hash references specifying access numbers.  Normally you can just pass the value of the I<svc_acct_pop> field returned by B<signup_info>.
1510
1511 =back
1512
1513 Returns an HTML fragment for access number selection.
1514
1515 =cut
1516
1517 #horrible false laziness with FS/FS/svc_acct_pop.pm::popselector
1518 sub popselector {
1519   my $param;
1520   if ( ref($_[0]) ) {
1521     $param = shift;
1522   } else {
1523     $param = { @_ };
1524   }
1525   my $popnum = $param->{'popnum'};
1526   my $pops = $param->{'pops'};
1527
1528   return '<INPUT TYPE="hidden" NAME="popnum" VALUE="">' unless @$pops;
1529   return $pops->[0]{city}. ', '. $pops->[0]{state}.
1530          ' ('. $pops->[0]{ac}. ')/'. $pops->[0]{exch}. '-'. $pops->[0]{loc}.
1531          '<INPUT TYPE="hidden" NAME="popnum" VALUE="'. $pops->[0]{popnum}. '">'
1532     if scalar(@$pops) == 1;
1533
1534   my %pop = ();
1535   my %popnum2pop = ();
1536   foreach (@$pops) {
1537     push @{ $pop{ $_->{state} }->{ $_->{ac} } }, $_;
1538     $popnum2pop{$_->{popnum}} = $_;
1539   }
1540
1541   my $text = <<END;
1542     <SCRIPT>
1543     function opt(what,href,text) {
1544       var optionName = new Option(text, href, false, false)
1545       var length = what.length;
1546       what.options[length] = optionName;
1547     }
1548 END
1549
1550   my $init_popstate = $param->{'init_popstate'};
1551   if ( $init_popstate ) {
1552     $text .= '<INPUT TYPE="hidden" NAME="init_popstate" VALUE="'.
1553              $init_popstate. '">';
1554   } else {
1555     $text .= <<END;
1556       function acstate_changed(what) {
1557         state = what.options[what.selectedIndex].text;
1558         what.form.popac.options.length = 0
1559         what.form.popac.options[0] = new Option("Area code", "-1", false, true);
1560 END
1561   }
1562
1563   my @states = $init_popstate ? ( $init_popstate ) : keys %pop;
1564   foreach my $state ( sort { $a cmp $b } @states ) {
1565     $text .= "\nif ( state == \"$state\" ) {\n" unless $init_popstate;
1566
1567     foreach my $ac ( sort { $a cmp $b } keys %{ $pop{$state} }) {
1568       $text .= "opt(what.form.popac, \"$ac\", \"$ac\");\n";
1569       if ($ac eq $param->{'popac'}) {
1570         $text .= "what.form.popac.options[what.form.popac.length-1].selected = true;\n";
1571       }
1572     }
1573     $text .= "}\n" unless $init_popstate;
1574   }
1575   $text .= "popac_changed(what.form.popac)}\n";
1576
1577   $text .= <<END;
1578   function popac_changed(what) {
1579     ac = what.options[what.selectedIndex].text;
1580     what.form.popnum.options.length = 0;
1581     what.form.popnum.options[0] = new Option("City", "-1", false, true);
1582
1583 END
1584
1585   foreach my $state ( @states ) {
1586     foreach my $popac ( keys %{ $pop{$state} } ) {
1587       $text .= "\nif ( ac == \"$popac\" ) {\n";
1588
1589       foreach my $pop ( @{$pop{$state}->{$popac}}) {
1590         my $o_popnum = $pop->{popnum};
1591         my $poptext =  $pop->{city}. ', '. $pop->{state}.
1592                        ' ('. $pop->{ac}. ')/'. $pop->{exch}. '-'. $pop->{loc};
1593
1594         $text .= "opt(what.form.popnum, \"$o_popnum\", \"$poptext\");\n";
1595         if ($popnum == $o_popnum) {
1596           $text .= "what.form.popnum.options[what.form.popnum.length-1].selected = true;\n";
1597         }
1598       }
1599       $text .= "}\n";
1600     }
1601   }
1602
1603
1604   $text .= "}\n</SCRIPT>\n";
1605
1606   $text .=
1607     qq!<TABLE CELLPADDING="0"><TR><TD><SELECT NAME="acstate"! .
1608     qq!SIZE=1 onChange="acstate_changed(this)"><OPTION VALUE=-1>State!;
1609   $text .= "<OPTION" . ($_ eq $param->{'acstate'} ? " SELECTED" : "") .
1610            ">$_" foreach sort { $a cmp $b } @states;
1611   $text .= '</SELECT>'; #callback? return 3 html pieces?  #'</TD>';
1612
1613   $text .=
1614     qq!<SELECT NAME="popac" SIZE=1 onChange="popac_changed(this)">!.
1615     qq!<OPTION>Area code</SELECT></TR><TR VALIGN="top">!;
1616
1617   $text .= qq!<TR><TD><SELECT NAME="popnum" SIZE=1 STYLE="width: 20em"><OPTION>City!;
1618
1619
1620   #comment this block to disable initial list polulation
1621   my @initial_select = ();
1622   if ( scalar( @$pops ) > 100 ) {
1623     push @initial_select, $popnum2pop{$popnum} if $popnum2pop{$popnum};
1624   } else {
1625     @initial_select = @$pops;
1626   }
1627   foreach my $pop ( sort { $a->{state} cmp $b->{state} } @initial_select ) {
1628     $text .= qq!<OPTION VALUE="!. $pop->{popnum}. '"'.
1629              ( ( $popnum && $pop->{popnum} == $popnum ) ? ' SELECTED' : '' ). ">".
1630              $pop->{city}. ', '. $pop->{state}.
1631                ' ('. $pop->{ac}. ')/'. $pop->{exch}. '-'. $pop->{loc};
1632   }
1633
1634   $text .= qq!</SELECT></TD></TR></TABLE>!;
1635
1636   $text;
1637
1638 }
1639
1640 =item domainselector HASHREF | LIST
1641
1642 Takes as input a hashref or list of key/value pairs with the following keys:
1643
1644 =over 4
1645
1646 =item pkgnum
1647
1648 Package number
1649
1650 =item domsvc
1651
1652 Service number of the selected item.
1653
1654 =back
1655
1656 Returns an HTML fragment for domain selection.
1657
1658 =cut
1659
1660 sub domainselector {
1661   my $param;
1662   if ( ref($_[0]) ) {
1663     $param = shift;
1664   } else {
1665     $param = { @_ };
1666   }
1667   my $domsvc= $param->{'domsvc'};
1668   my $rv =
1669       domain_select_hash(map {$_ => $param->{$_}} qw(pkgnum svcpart pkgpart) );
1670   my $domains = $rv->{'domains'};
1671   $domsvc = $rv->{'domsvc'} unless $domsvc;
1672
1673   return '<INPUT TYPE="hidden" NAME="domsvc" VALUE="">'
1674     unless scalar(keys %$domains);
1675
1676   if (scalar(keys %$domains) == 1) {
1677     my $key;
1678     foreach(keys %$domains) {
1679       $key = $_;
1680     }
1681     return '<TR><TD ALIGN="right">Domain</TD><TD>'. $domains->{$key}.
1682            '<INPUT TYPE="hidden" NAME="domsvc" VALUE="'. $key. '"></TD></TR>'
1683   }
1684
1685   my $text .= qq!<TR><TD ALIGN="right">Domain</TD><TD><SELECT NAME="domsvc" SIZE=1 STYLE="width: 20em"><OPTION>(Choose Domain)!;
1686
1687
1688   foreach my $domain ( sort { $domains->{$a} cmp $domains->{$b} } keys %$domains ) {
1689     $text .= qq!<OPTION VALUE="!. $domain. '"'.
1690              ( ( $domsvc && $domain == $domsvc ) ? ' SELECTED' : '' ). ">".
1691              $domains->{$domain};
1692   }
1693
1694   $text .= qq!</SELECT></TD></TR>!;
1695
1696   $text;
1697
1698 }
1699
1700 =item didselector HASHREF | LIST
1701
1702 Takes as input a hashref or list of key/value pairs with the following keys:
1703
1704 =over 4
1705
1706 =item field
1707
1708 Field name for the returned HTML fragment.
1709
1710 =item svcpart
1711
1712 Service definition (see L<FS::part_svc>)
1713
1714 =back
1715
1716 Returns an HTML fragment for DID selection.
1717
1718 =cut
1719
1720 sub didselector {
1721   my $param;
1722   if ( ref($_[0]) ) {
1723     $param = shift;
1724   } else {
1725     $param = { @_ };
1726   }
1727
1728   my $rv = mason_comp( 'comp'=>'/elements/select-did.html',
1729                        'args'=>[ %$param ],
1730                      );
1731
1732   #hmm.
1733   $rv->{'error'} || $rv->{'output'};
1734
1735 }
1736
1737 =back
1738
1739 =head1 RESELLER FUNCTIONS
1740
1741 Note: Resellers can also use the B<signup_info> and B<new_customer> functions
1742 with their active session, and the B<customer_info> and B<order_pkg> functions
1743 with their active session and an additional I<custnum> parameter.
1744
1745 For the most part, development of the reseller web interface has been
1746 superceded by agent-virtualized access to the backend.
1747
1748 =over 4
1749
1750 =item agent_login
1751
1752 Agent login
1753
1754 =item agent_info
1755
1756 Agent info
1757
1758 =item agent_list_customers
1759
1760 List agent's customers.
1761
1762 =back
1763
1764 =head1 BUGS
1765
1766 =head1 SEE ALSO
1767
1768 L<freeside-selfservice-clientd>, L<freeside-selfservice-server>
1769
1770 =cut
1771
1772 1;
1773