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_banner_image'        => 'MyAccount/login_banner_image',
  30   'login'                     => 'MyAccount/login',
  31   'logout'                    => 'MyAccount/logout',
  32   'switch_acct'               => 'MyAccount/switch_acct',
  33   'switch_cust'               => 'MyAccount/switch_cust',
  34   'customer_info'             => 'MyAccount/customer_info',
  35   'customer_info_short'       => 'MyAccount/customer_info_short',
  36
  37   'contact_passwd'            => 'MyAccount/contact/contact_passwd',
  38   'list_contacts'             => 'MyAccount/contact/list_contacts',
  39   'edit_contact'              => 'MyAccount/contact/edit_contact',
  40   'delete_contact'            => 'MyAccount/contact/delete_contact',
  41   'new_contact'               => 'MyAccount/contact/new_contact',
  42
  43   'billing_history'           => 'MyAccount/billing_history',
  44   'edit_info'                 => 'MyAccount/edit_info',     #add to ss cgi!
  45   'invoice'                   => 'MyAccount/invoice',
  46   'invoice_pdf'               => 'MyAccount/invoice_pdf',
  47   'legacy_invoice'            => 'MyAccount/legacy_invoice',
  48   'legacy_invoice_pdf'        => 'MyAccount/legacy_invoice_pdf',
  49   'invoice_logo'              => 'MyAccount/invoice_logo',
  50   'list_invoices'             => 'MyAccount/list_invoices', #?
  51   'list_payby'                => 'MyAccount/list_payby',
  52   'insert_payby'              => 'MyAccount/insert_payby',
  53   'delete_payby'              => 'MyAccount/delete_payby',
  54   'cancel'                    => 'MyAccount/cancel',        #add to ss cgi!
  55   'payment_info'              => 'MyAccount/payment_info',
  56   'payment_info_renew_info'   => 'MyAccount/payment_info_renew_info',
  57   'process_payment'           => 'MyAccount/process_payment',
  58   'store_payment'             => 'MyAccount/store_payment',
  59   'process_stored_payment'    => 'MyAccount/process_stored_payment',
  60   'process_payment_order_pkg' => 'MyAccount/process_payment_order_pkg',
  61   'process_payment_change_pkg' => 'MyAccount/process_payment_change_pkg',
  62   'process_payment_order_renew' => 'MyAccount/process_payment_order_renew',
  63   'process_prepay'            => 'MyAccount/process_prepay',
  64   'realtime_collect'          => 'MyAccount/realtime_collect',
  65   'list_pkgs'                 => 'MyAccount/list_pkgs',     #add to ss (added?)
  66   'list_svcs'                 => 'MyAccount/list_svcs',     #add to ss (added?)
  67   'list_svc_usage'            => 'MyAccount/list_svc_usage',
  68   'svc_status_html'           => 'MyAccount/svc_status_html',
  69   'svc_status_hash'           => 'MyAccount/svc_status_hash',
  70   'set_svc_status_hash'       => 'MyAccount/set_svc_status_hash',
  71   'set_svc_status_listadd'    => 'MyAccount/set_svc_status_listadd',
  72   'set_svc_status_listdel'    => 'MyAccount/set_svc_status_listdel',
  73   'set_svc_status_vacationadd'=> 'MyAccount/set_svc_status_vacationadd',
  74   'set_svc_status_vacationdel'=> 'MyAccount/set_svc_status_vacationdel',
  75   'acct_forward_info'         => 'MyAccount/acct_forward_info',
  76   'process_acct_forward'      => 'MyAccount/process_acct_forward',
  77   'list_dsl_devices'          => 'MyAccount/list_dsl_devices',
  78   'add_dsl_device'            => 'MyAccount/add_dsl_device',
  79   'delete_dsl_device'         => 'MyAccount/delete_dsl_device',
  80   'port_graph'                => 'MyAccount/port_graph',
  81   'list_cdr_usage'            => 'MyAccount/list_cdr_usage',
  82   'list_support_usage'        => 'MyAccount/list_support_usage',
  83   'order_pkg'                 => 'MyAccount/order_pkg',     #add to ss cgi!
  84   'change_pkg'                => 'MyAccount/change_pkg',
  85   'order_recharge'            => 'MyAccount/order_recharge',
  86   'renew_info'                => 'MyAccount/renew_info',
  87   'order_renew'               => 'MyAccount/order_renew',
  88   'cancel_pkg'                => 'MyAccount/cancel_pkg',    #add to ss cgi!
  89   'suspend_pkg'               => 'MyAccount/suspend_pkg',   #add to ss cgi!
  90   'charge'                    => 'MyAccount/charge',        #?
  91   'part_svc_info'             => 'MyAccount/part_svc_info',
  92   'provision_acct'            => 'MyAccount/provision_acct',
  93   'provision_phone'           => 'MyAccount/provision_phone',
  94   'provision_pbx'             => 'MyAccount/provision_pbx',
  95   'provision_external'        => 'MyAccount/provision_external',
  96   'provision_forward'         => 'MyAccount/provision_forward',
  97   'unprovision_svc'           => 'MyAccount/unprovision_svc',
  98   'myaccount_passwd'          => 'MyAccount/myaccount_passwd',
  99   'reset_passwd'              => 'MyAccount/reset_passwd',
 100   'check_reset_passwd'        => 'MyAccount/check_reset_passwd',
 101   'process_reset_passwd'      => 'MyAccount/process_reset_passwd',
 102   'validate_passwd'           => 'MyAccount/validate_passwd',
 103   'list_tickets'              => 'MyAccount/list_tickets',
 104   'create_ticket'             => 'MyAccount/create_ticket',
 105   'get_ticket'                => 'MyAccount/get_ticket',
 106   'adjust_ticket_priority'    => 'MyAccount/adjust_ticket_priority',
 107   'did_report'                => 'MyAccount/did_report',
 108   'signup_info'               => 'Signup/signup_info',
 109   'skin_info'                 => 'MyAccount/skin_info',
 110   'access_info'               => 'MyAccount/access_info',
 111   'domain_select_hash'        => 'Signup/domain_select_hash',  # expose?
 112   'new_customer'              => 'Signup/new_customer',
 113   'new_customer_minimal'      => 'Signup/new_customer_minimal',
 114   'capture_payment'           => 'Signup/capture_payment',
 115   #N/A 'clear_signup_cache'        => 'Signup/clear_cache',
 116   'new_agent'                 => 'Agent/new_agent',
 117   'agent_login'               => 'Agent/agent_login',
 118   'agent_logout'              => 'Agent/agent_logout',
 119   'agent_info'                => 'Agent/agent_info',
 120   'agent_list_customers'      => 'Agent/agent_list_customers',
 121   'check_username'            => 'Agent/check_username',
 122   'suspend_username'          => 'Agent/suspend_username',
 123   'unsuspend_username'        => 'Agent/unsuspend_username',
 124   'mason_comp'                => 'MasonComponent/mason_comp',
 125   'call_time'                 => 'PrepaidPhone/call_time',
 126   'call_time_nanpa'           => 'PrepaidPhone/call_time_nanpa',
 127   'phonenum_balance'          => 'PrepaidPhone/phonenum_balance',
 128
 129   'start_thirdparty'          => 'MyAccount/start_thirdparty',
 130   'finish_thirdparty'         => 'MyAccount/finish_thirdparty',
 131
 132   'list_quotations'           => 'MyAccount/quotation/list_quotations',
 133   'quotation_new'             => 'MyAccount/quotation/quotation_new',
 134   'quotation_delete'          => 'MyAccount/quotation/quotation_delete',
 135   'quotation_info'            => 'MyAccount/quotation/quotation_info',
 136   'quotation_print'           => 'MyAccount/quotation/quotation_print',
 137   'quotation_add_pkg'         => 'MyAccount/quotation/quotation_add_pkg',
 138   'quotation_remove_pkg'      => 'MyAccount/quotation/quotation_remove_pkg',
 139   'quotation_order'           => 'MyAccount/quotation/quotation_order',
 140
 141   'freesideinc_service'       => 'Freeside/freesideinc_service',
 142
 143 );
 144 @EXPORT_OK = (
 145   keys(%autoload),
 146   qw( regionselector regionselector_hashref location_form
 147       expselect popselector domainselector didselector
 148     )
 149 );
 150
 151 $ENV{'PATH'} ='/usr/bin:/usr/ucb:/bin';
 152 $ENV{'SHELL'} = '/bin/sh';
 153 $ENV{'IFS'} = " \t\n";
 154 $ENV{'CDPATH'} = '';
 155 $ENV{'ENV'} = '';
 156 $ENV{'BASH_ENV'} = '';
 157
 158 #you can add BEGIN { $FS::SelfService::skip_uid_check = 1; }
 159 #if you grant appropriate permissions to whatever user
 160 my $freeside_uid = scalar(getpwnam('freeside'));
 161 die "not running as the freeside user\n"
 162   if $> != $freeside_uid && ! $skip_uid_check;
 163
 164 -e $dir or die "FATAL: $dir doesn't exist!";
 165 -d $dir or die "FATAL: $dir isn't a directory!";
 166 -r $dir or die "FATAL: Can't read $dir as freeside user!";
 167 -x $dir or die "FATAL: $dir not searchable (executable) as freeside user!";
 168
 169 foreach my $autoload ( keys %autoload ) {
 170
 171   my $eval =
 172   "sub $autoload { ". '
 173                    my $param;
 174                    if ( ref($_[0]) ) {
 175                      $param = shift;
 176                    } else {
 177                      #warn scalar(@_). ": ". join(" / ", @_);
 178                      $param = { @_ };
 179                    }
 180
 181                    $param->{_packet} = \''. $autoload{$autoload}. '\';
 182
 183                    simple_packet($param);
 184                  }';
 185
 186   eval $eval;
 187   die $@ if $@;
 188
 189 }
 190
 191 sub simple_packet {
 192   my $packet = shift;
 193   warn "sending ". $packet->{_packet}. " to server"
 194     if $DEBUG;
 195   socket(SOCK, PF_UNIX, SOCK_STREAM, 0) or die "socket: $!";
 196   connect(SOCK, sockaddr_un($socket)) or die "connect to $socket: $!";
 197   nstore_fd($packet, \*SOCK) or die "can't send packet: $!";
 198   SOCK->flush;
 199
 200   #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
 201
 202   #block until there is a message on socket
 203 #  my $w = new IO::Select;
 204 #  $w->add(\*SOCK);
 205 #  my @wait = $w->can_read;
 206
 207   warn "reading message from server"
 208     if $DEBUG;
 209
 210   my $return = fd_retrieve(\*SOCK) or die "error reading result: $!";
 211   die $return->{'_error'} if defined $return->{_error} && $return->{_error};
 212
 213   warn "returning message to client"
 214     if $DEBUG;
 215
 216   $return;
 217 }
 218
 219 =head1 NAME
 220
 221 FS::SelfService - Freeside self-service API
 222
 223 =head1 SYNOPSIS
 224
 225   # password and shell account changes
 226   use FS::SelfService qw(passwd chfn chsh);
 227
 228   # "my account" functionality
 229   use FS::SelfService qw( login customer_info invoice cancel payment_info process_payment );
 230
 231   #new-style login with an email address and password
 232   # can also be used for svc_acct login, set $emailaddress to username@domain
 233   my $rv = login ( { 'email'    => $emailaddress,
 234                      'password' => $password,
 235                    },
 236                  );
 237   if ( $rv->{'error'} ) {
 238     #handle login error...
 239   } else {
 240     #successful login
 241     $session_id = $rv->{'session_id'};
 242   }
 243
 244   #classic svc_acct-based login with separate username and password
 245   my $rv = login( { 'username' => $username,
 246                     'domain'   => $domain,
 247                     'password' => $password,
 248                   }
 249                 );
 250   if ( $rv->{'error'} ) {
 251     #handle login error...
 252   } else {
 253     #successful login
 254     $session_id = $rv->{'session_id'};
 255   }
 256
 257   #svc_phone login with phone number and PIN
 258   my $rv = login( { 'username' => $phone_number,
 259                     'domain'   => 'svc_phone',
 260                     'password' => $pin,
 261                   }
 262                 );
 263   if ( $rv->{'error'} ) {
 264     #handle login error...
 265   } else {
 266     #successful login
 267     $session_id = $rv->{'session_id'};
 268   }
 269
 270   my $customer_info = customer_info( { 'session_id' => $session_id } );
 271
 272   #payment_info and process_payment are available in 1.5+ only
 273   my $payment_info = payment_info( { 'session_id' => $session_id } );
 274
 275   #!!! process_payment example
 276
 277   #!!! list_pkgs example
 278
 279   #ordering a package with an svc_acct service
 280   my $rv = order_pkg( { 'session_id' => $session_id,
 281                         'pkgpart'    => $pkgpart,
 282                         'svcpart'    => $svcpart,
 283                         'username'   => $username,
 284                         'domsvc'     => $domsvc, #svcnum of svc_domain
 285                         '_password'  => $password,
 286                       }
 287                     );
 288
 289   #!!! ordering a package with an svc_domain service example
 290
 291   #!!! ordering a package with an svc_phone service example
 292
 293   #!!! ordering a package with an svc_external service example
 294
 295   #!!! ordering a package with an svc_pbx service
 296
 297   #ordering a package with no service
 298   my $rv = order_pkg( { 'session_id' => $session_id,
 299                         'pkgpart'    => $pkgpart,
 300                         'svcpart'    => 'none',
 301                       }
 302                     );
 303
 304   #quoting a package, then ordering after confirmation
 305
 306   my $rv = quotation_new({ 'session_id' => $session_id });
 307   my $qnum = $rv->{quotationnum};
 308   #  add packages to the quotation
 309   $rv = quotation_add_pkg({ 'session_id'   => $session_id,
 310                             'quotationnum' => $qnum,
 311                             'pkgpart'      => $pkgpart,
 312                             'quantity'     => $quantity, # defaults to 1
 313                           });
 314   #  repeat until all packages are added
 315   #  view the pricing information
 316   $rv = quotation_info({ 'session_id'   => $session_id,
 317                          'quotationnum' => $qnum,
 318                       });
 319   print "Total setup charges: ".$rv->{total_setup}."\n".
 320         "Total recurring charges: ".$rv->{total_recur}."\n";
 321   #  quotation_info also provides a detailed breakdown of charges, in
 322   #  $rv->{sections}.
 323
 324   #  ask customer for confirmation, then:
 325   $rv = quotation_order({ 'session_id'   => $session_id,
 326                           'quotationnum' => $qnum,
 327                         });
 328
 329   #!!! cancel_pkg example
 330
 331   # signup functionality
 332   use FS::SelfService qw( signup_info new_customer new_customer_minimal );
 333
 334   my $signup_info = signup_info;
 335
 336   $rv = new_customer( {
 337                         'first'            => $first,
 338                         'last'             => $last,
 339                         'company'          => $company,
 340                         'address1'         => $address1,
 341                         'address2'         => $address2,
 342                         'city'             => $city,
 343                         'state'            => $state,
 344                         'zip'              => $zip,
 345                         'country'          => $country,
 346                         'daytime'          => $daytime,
 347                         'night'            => $night,
 348                         'fax'              => $fax,
 349                         'payby'            => $payby,
 350                         'payinfo'          => $payinfo,
 351                         'paycvv'           => $paycvv,
 352                         'paystart_month'   => $paystart_month
 353                         'paystart_year'    => $paystart_year,
 354                         'payissue'         => $payissue,
 355                         'payip'            => $payip
 356                         'paydate'          => $paydate,
 357                         'payname'          => $payname,
 358                         'invoicing_list'   => $invoicing_list,
 359                         'referral_custnum' => $referral_custnum,
 360                         'agentnum'         => $agentnum,
 361                         'pkgpart'          => $pkgpart,
 362
 363                         'username'         => $username,
 364                         '_password'        => $password,
 365                         'popnum'           => $popnum,
 366                         #OR
 367                         'countrycode'      => 1,
 368                         'phonenum'         => $phonenum,
 369                         'pin'              => $pin,
 370                       }
 371                     );
 372
 373   my $error = $rv->{'error'};
 374   if ( $error eq '_decline' ) {
 375     print_decline();
 376   } elsif ( $error ) {
 377     reprint_signup();
 378   } else {
 379     print_success();
 380   }
 381
 382 =head1 DESCRIPTION
 383
 384 Use this API to implement your own client "self-service" module.
 385
 386 If you just want to customize the look of the existing "self-service" module,
 387 see XXXX instead.
 388
 389 =head1 PASSWORD, GECOS, SHELL CHANGING FUNCTIONS
 390
 391 =over 4
 392
 393 =item passwd
 394
 395 Changes the password for an existing user in svc_acct.  Takes a hash
 396 reference with the following keys:
 397
 398 =over 4
 399
 400 =item username
 401
 402 Username of the account (required)
 403
 404 =item domain
 405
 406 Domain of the account (required)
 407
 408 =item old_password
 409
 410 Old password (required)
 411
 412 =item new_password
 413
 414 New password (required)
 415
 416 =item new_gecos
 417
 418 New gecos
 419
 420 =item new_shell
 421
 422 New Shell
 423
 424 =back
 425
 426 =item chfn
 427
 428 =item chsh
 429
 430 =back
 431
 432 =head1 "MY ACCOUNT" FUNCTIONS
 433
 434 =over 4
 435
 436 =item login HASHREF
 437
 438 Creates a user session.  Takes a hash reference as parameter with the
 439 following keys:
 440
 441 =over 4
 442
 443 =item email
 444
 445 Email address (username@domain), instead of username and domain.  Required for
 446 contact-based self-service login, can also be used for svc_acct-based login.
 447
 448 =item username
 449
 450 Username
 451
 452 =item domain
 453
 454 Domain
 455
 456 =item password
 457
 458 Password
 459
 460 =back
 461
 462 Returns a hash reference with the following keys:
 463
 464 =over 4
 465
 466 =item error
 467
 468 Empty on success, or an error message on errors.
 469
 470 =item session_id
 471
 472 Session identifier for successful logins
 473
 474 =back
 475
 476 =item customer_info HASHREF
 477
 478 Returns general customer information.
 479
 480 Takes a hash reference as parameter with a single key: B<session_id>
 481
 482 Returns a hash reference with the following keys:
 483
 484 =over 4
 485
 486 =item name
 487
 488 Customer name
 489
 490 =item balance
 491
 492 Balance owed
 493
 494 =item open
 495
 496 Array reference of hash references of open inoices.  Each hash reference has
 497 the following keys: invnum, date, owed
 498
 499 =item small_custview
 500
 501 An HTML fragment containing shipping and billing addresses.
 502
 503 =item The following fields are also returned
 504
 505 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
 506
 507 =back
 508
 509 =item edit_info HASHREF
 510
 511 Takes a hash reference as parameter with any of the following keys:
 512
 513 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
 514
 515 If a field exists, the customer record is updated with the new value of that
 516 field.  If a field does not exist, that field is not changed on the customer
 517 record.
 518
 519 Returns a hash reference with a single key, B<error>, empty on success, or an
 520 error message on errors
 521
 522 =item invoice HASHREF
 523
 524 Returns an invoice.  Takes a hash reference as parameter with two keys:
 525 session_id and invnum
 526
 527 Returns a hash reference with the following keys:
 528
 529 =over 4
 530
 531 =item error
 532
 533 Empty on success, or an error message on errors
 534
 535 =item invnum
 536
 537 Invoice number
 538
 539 =item invoice_text
 540
 541 Invoice text
 542
 543 =back
 544
 545 =item list_invoices HASHREF
 546
 547 Returns a list of all customer invoices.  Takes a hash reference with a single
 548 key, session_id.
 549
 550 Returns a hash reference with the following keys:
 551
 552 =over 4
 553
 554 =item error
 555
 556 Empty on success, or an error message on errors
 557
 558 =item invoices
 559
 560 Reference to array of hash references with the following keys:
 561
 562 =over 4
 563
 564 =item invnum
 565
 566 Invoice ID
 567
 568 =item _date
 569
 570 Invoice date, in UNIX epoch time
 571
 572 =back
 573
 574 =back
 575
 576 =item list_payby HASHREF
 577
 578 Returns a list of all stored customer payment information (credit cards and
 579 electronic check accounts).  Takes a hash reference with a single key,
 580 session_id.
 581
 582 Returns a hash reference with the following keys:
 583
 584 =over 4
 585
 586 =item error
 587
 588 Empty on success, or an error message on errors
 589
 590 =item payby
 591
 592 Reference to array of hash references with the following keys:
 593
 594 =over 4
 595
 596 =item custpaybynum
 597
 598 =item weight
 599
 600 Numeric weighting.  Stored payment information with a lower weight is attempted
 601 first.
 602
 603 =item payby
 604
 605 CARD (Automatic credit card), CHEK (Automatic electronic check), DCRD
 606 (on-demand credit card) or DCHK (on-demand electronic check).
 607
 608 =item paymask
 609
 610 Masked credit card number (or, masked account and routing numbers)
 611
 612 =item paydate
 613
 614 Credit card expiration date
 615
 616 =item payname
 617
 618 Exact name on card (or bank name, for electronic checks)
 619
 620 =item paystate
 621
 622 For electronic checks, bank state
 623
 624 =item paytype
 625
 626 For electronic checks, account type (Personal/Business, Checking/Savings)
 627
 628 =back
 629
 630 =back
 631
 632 =item insert_payby HASHREF
 633
 634 Adds new stored payment information for this customer.  Takes a hash reference
 635 with the following keys:
 636
 637 =over 4
 638
 639 =item session_id
 640
 641 =item weight
 642
 643 Numeric weighting.  Stored payment information with a lower weight is attempted
 644 first.
 645
 646 =item payby
 647
 648 CARD (Automatic credit card), CHEK (Automatic electronic check), DCRD
 649 (on-demand credit card) or DCHK (on-demand electronic check).
 650
 651 =item payinfo
 652
 653 Credit card number (or electronic check "account@routing")
 654
 655 =item paycvv
 656
 657 CVV2 number / security code
 658
 659 =item paydate
 660
 661 Credit card expiration date
 662
 663 =item payname
 664
 665 Exact name on card (or bank name, for electronic checks)
 666
 667 =item paystate
 668
 669 For electronic checks, bank state
 670
 671 =item paytype
 672
 673 For electronic checks, account type (i.e. "Personal Savings", "Personal Checking", "Business Checking")A
 674
 675 =item payip
 676
 677 Optional IP address from which payment was submitted
 678
 679 =back
 680
 681 If there is an error, returns a hash reference with a single key, B<error>,
 682 otherwise returns a hash reference with a single key, B<custpaybynum>.
 683
 684 =item delete_payby HASHREF
 685
 686 Removes stored payment information.  Takes a hash reference with two keys,
 687 B<session_id> and B<custpaybynum>.  Returns a hash reference with a single key,
 688 B<error>, which is an error message or empty for successful removal.
 689
 690 =item cancel HASHREF
 691
 692 Cancels this customer.
 693
 694 Takes a hash reference as parameter with a single key: B<session_id>
 695
 696 Returns a hash reference with a single key, B<error>, which is empty on
 697 success or an error message on errors.
 698
 699 =item payment_info HASHREF
 700
 701 Returns information that may be useful in displaying a payment page.
 702
 703 Takes a hash reference as parameter with a single key: B<session_id>.
 704
 705 Returns a hash reference with the following keys:
 706
 707 =over 4
 708
 709 =item error
 710
 711 Empty on success, or an error message on errors
 712
 713 =item balance
 714
 715 Balance owed
 716
 717 =item payname
 718
 719 Exact name on credit card (CARD/DCRD)
 720
 721 =item address1
 722
 723 Address line one
 724
 725 =item address2
 726
 727 Address line two
 728
 729 =item city
 730
 731 City
 732
 733 =item state
 734
 735 State
 736
 737 =item zip
 738
 739 Zip or postal code
 740
 741 =item payby
 742
 743 Customer's current default payment type.
 744
 745 =item card_type
 746
 747 For CARD/DCRD payment types, the card type (Visa card, MasterCard, Discover card, American Express card, etc.)
 748
 749 =item payinfo
 750
 751 For CARD/DCRD payment types, the card number
 752
 753 =item month
 754
 755 For CARD/DCRD payment types, expiration month
 756
 757 =item year
 758
 759 For CARD/DCRD payment types, expiration year
 760
 761 =item cust_main_county
 762
 763 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.
 764
 765 =item states
 766
 767 Array reference of all states in the current default country.
 768
 769 =item card_types
 770
 771 Hash reference of card types; keys are card types, values are the exact strings
 772 passed to the process_payment function
 773
 774 =cut
 775
 776 #this doesn't actually work yet
 777 #
 778 #=item paybatch
 779 #
 780 #Unique transaction identifier (prevents multiple charges), passed to the
 781 #process_payment function
 782
 783 =back
 784
 785 =item process_payment HASHREF
 786
 787 Processes a payment and possible change of address or payment type.  Takes a
 788 hash reference as parameter with the following keys:
 789
 790 =over 4
 791
 792 =item session_id
 793
 794 Session identifier
 795
 796 =item amount
 797
 798 Amount
 799
 800 =item save
 801
 802 If true, address and card information entered will be saved for subsequent
 803 transactions.
 804
 805 =item auto
 806
 807 If true, future credit card payments will be done automatically (sets payby to
 808 CARD).  If false, future credit card payments will be done on-demand (sets
 809 payby to DCRD).  This option only has meaning if B<save> is set true.
 810
 811 =item payname
 812
 813 Name on card
 814
 815 =item address1
 816
 817 Address line one
 818
 819 =item address2
 820
 821 Address line two
 822
 823 =item city
 824
 825 City
 826
 827 =item state
 828
 829 State
 830
 831 =item zip
 832
 833 Zip or postal code
 834
 835 =item country
 836
 837 Two-letter country code
 838
 839 =item payinfo
 840
 841 Card number
 842
 843 =item month
 844
 845 Card expiration month
 846
 847 =item year
 848
 849 Card expiration year
 850
 851 =cut
 852
 853 #this doesn't actually work yet
 854 #
 855 #=item paybatch
 856 #
 857 #Unique transaction identifier, returned from the payment_info function.
 858 #Prevents multiple charges.
 859
 860 =back
 861
 862 Returns a hash reference with a single key, B<error>, empty on success, or an
 863 error message on errors.
 864
 865 =item process_payment_order_pkg
 866
 867 Combines the B<process_payment> and B<order_pkg> functions in one step.  If the
 868 payment processes sucessfully, the package is ordered.  Takes a hash reference
 869 as parameter with the keys of both methods.
 870
 871 Returns a hash reference with a single key, B<error>, empty on success, or an
 872 error message on errors.
 873
 874 =item process_payment_change_pkg
 875
 876 Combines the B<process_payment> and B<change_pkg> functions in one step.  If the
 877 payment processes sucessfully, the package is ordered.  Takes a hash reference
 878 as parameter with the keys of both methods.
 879
 880 Returns a hash reference with a single key, B<error>, empty on success, or an
 881 error message on errors.
 882
 883
 884 =item process_payment_order_renew
 885
 886 Combines the B<process_payment> and B<order_renew> functions in one step.  If
 887 the payment processes sucessfully, the renewal is processed.  Takes a hash
 888 reference as parameter with the keys of both methods.
 889
 890 Returns a hash reference with a single key, B<error>, empty on success, or an
 891 error message on errors.
 892
 893 =item list_pkgs
 894
 895 Returns package information for this customer.  For more detail on services,
 896 see L</list_svcs>.
 897
 898 Takes a hash reference as parameter with a single key: B<session_id>
 899
 900 Returns a hash reference containing customer package information.  The hash reference contains the following keys:
 901
 902 =over 4
 903
 904 =item custnum
 905
 906 Customer number
 907
 908 =item error
 909
 910 Empty on success, or an error message on errors.
 911
 912 =item cust_pkg HASHREF
 913
 914 Array reference of hash references, each of which has the fields of a cust_pkg
 915 record (see L<FS::cust_pkg>) as well as the fields below.  Note these are not
 916 the internal FS:: objects, but hash references of columns and values.
 917
 918 =over 4
 919
 920 =item part_pkg fields
 921
 922 All fields of part_pkg for this specific cust_pkg (be careful with this
 923 information - it may reveal more about your available packages than you would
 924 like users to know in aggregate)
 925
 926 =cut
 927
 928 #XXX pare part_pkg fields down to a more secure subset
 929
 930 =item part_svc
 931
 932 An array of hash references indicating information on unprovisioned services
 933 available for provisioning for this specific cust_pkg.  Each has the following
 934 keys:
 935
 936 =over 4
 937
 938 =item part_svc fields
 939
 940 All fields of part_svc (be careful with this information - it may reveal more
 941 about your available packages than you would like users to know in aggregate)
 942
 943 =cut
 944
 945 #XXX pare part_svc fields down to a more secure subset
 946
 947 =back
 948
 949 =item cust_svc
 950
 951 An array of hash references indicating information on the customer services
 952 already provisioned for this specific cust_pkg.  Each has the following keys:
 953
 954 =over 4
 955
 956 =item label
 957
 958 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.
 959
 960 =back
 961
 962 =item svcnum
 963
 964 Primary key for this service
 965
 966 =item svcpart
 967
 968 Service definition (see L<FS::part_svc>)
 969
 970 =item pkgnum
 971
 972 Customer package (see L<FS::cust_pkg>)
 973
 974 =item overlimit
 975
 976 Blank if the service is not over limit, or the date the service exceeded its usage limit (as a UNIX timestamp).
 977
 978 =back
 979
 980 =back
 981
 982 =item list_svcs
 983
 984 Returns service information for this customer.
 985
 986 Takes a hash reference as parameter with a single key: B<session_id>
 987
 988 Returns a hash reference containing customer package information.  The hash reference contains the following keys:
 989
 990 =over 4
 991
 992 =item custnum
 993
 994 Customer number
 995
 996 =item svcs
 997
 998 An array of hash references indicating information on all of this customer's
 999 services.  Each has the following keys:
1000
1001 =over 4
1002
1003 =item svcnum
1004
1005 Primary key for this service
1006
1007 =item label
1008
1009 Name of this service
1010
1011 =item value
1012
1013 Meaningful user-specific identifier for the service (i.e. username, domain, or
1014 mail alias).
1015
1016 =back
1017
1018 Account (svc_acct) services also have the following keys:
1019
1020 =over 4
1021
1022 =item username
1023
1024 Username
1025
1026 =item email
1027
1028 username@domain
1029
1030 =item seconds
1031
1032 Seconds remaining
1033
1034 =item upbytes
1035
1036 Upload bytes remaining
1037
1038 =item downbytes
1039
1040 Download bytes remaining
1041
1042 =item totalbytes
1043
1044 Total bytes remaining
1045
1046 =item recharge_amount
1047
1048 Cost of a recharge
1049
1050 =item recharge_seconds
1051
1052 Number of seconds gained by recharge
1053
1054 =item recharge_upbytes
1055
1056 Number of upload bytes gained by recharge
1057
1058 =item recharge_downbytes
1059
1060 Number of download bytes gained by recharge
1061
1062 =item recharge_totalbytes
1063
1064 Number of total bytes gained by recharge
1065
1066 =back
1067
1068 =back
1069
1070 =item order_pkg
1071
1072 Orders a package for this customer.
1073
1074 Takes a hash reference as parameter with the following keys:
1075
1076 =over 4
1077
1078 =item session_id
1079
1080 Session identifier
1081
1082 =item pkgpart
1083
1084 Package to order (see L<FS::part_pkg>).
1085
1086 =item quantity
1087
1088 Quantity for this package order (default 1).
1089
1090 =item locationnum
1091
1092 Optional locationnum for this package order, for existing locations.
1093
1094 Or, for new locations, pass the following fields: address1*, address2, city*,
1095 county, state*, zip*, country.  (* = required in this case)
1096
1097 =item address1
1098
1099 =item address 2
1100
1101 =item city
1102
1103 =item
1104
1105 =item svcpart
1106
1107 Service to order (see L<FS::part_svc>).
1108
1109 Normally optional; required only to provision a non-svc_acct service, or if the
1110 package definition does not contain one svc_acct service definition with
1111 quantity 1 (it may contain others with quantity >1).  A svcpart of "none" can
1112 also be specified to indicate that no initial service should be provisioned.
1113
1114 =back
1115
1116 Fields used when provisioning an svc_acct service:
1117
1118 =over 4
1119
1120 =item username
1121
1122 Username
1123
1124 =item _password
1125
1126 Password
1127
1128 =item sec_phrase
1129
1130 Optional security phrase
1131
1132 =item popnum
1133
1134 Optional Access number number
1135
1136 =back
1137
1138 Fields used when provisioning an svc_domain service:
1139
1140 =over 4
1141
1142 =item domain
1143
1144 Domain
1145
1146 =back
1147
1148 Fields used when provisioning an svc_phone service:
1149
1150 =over 4
1151
1152 =item phonenum
1153
1154 Phone number
1155
1156 =item pin
1157
1158 Voicemail PIN
1159
1160 =item sip_password
1161
1162 SIP password
1163
1164 =back
1165
1166 Fields used when provisioning an svc_external service:
1167
1168 =over 4
1169
1170 =item id
1171
1172 External numeric ID.
1173
1174 =item title
1175
1176 External text title.
1177
1178 =back
1179
1180 Fields used when provisioning an svc_pbx service:
1181
1182 =over 4
1183
1184 =item id
1185
1186 Numeric ID.
1187
1188 =item name
1189
1190 Text name.
1191
1192 =back
1193
1194 Returns a hash reference with a single key, B<error>, empty on success, or an
1195 error message on errors.  The special error '_decline' is returned for
1196 declined transactions.
1197
1198 =item change_pkg
1199
1200 Changes a package for this customer.
1201
1202 Takes a hash reference as parameter with the following keys:
1203
1204 =over 4
1205
1206 =item session_id
1207
1208 Session identifier
1209
1210 =item pkgnum
1211
1212 Existing customer package.
1213
1214 =item pkgpart
1215
1216 New package to order (see L<FS::part_pkg>).
1217
1218 =item quantity
1219
1220 Quantity for this package order (default 1).
1221
1222 =back
1223
1224 Returns a hash reference with the following keys:
1225
1226 =over 4
1227
1228 =item error
1229
1230 Empty on success, or an error message on errors.
1231
1232 =item pkgnum
1233
1234 On success, the new pkgnum
1235
1236 =back
1237
1238
1239 =item renew_info
1240
1241 Provides useful info for early renewals.
1242
1243 Takes a hash reference as parameter with the following keys:
1244
1245 =over 4
1246
1247 =item session_id
1248
1249 Session identifier
1250
1251 =back
1252
1253 Returns a hash reference.  On errors, it contains a single key, B<error>, with
1254 the error message.  Otherwise, contains a single key, B<dates>, pointing to
1255 an array refernce of hash references.  Each hash reference contains the
1256 following keys:
1257
1258 =over 4
1259
1260 =item bill_date
1261
1262 (Future) Bill date.  Indicates a future date for which billing could be run.
1263 Specified as a integer UNIX timestamp.  Pass this value to the B<order_renew>
1264 function.
1265
1266 =item bill_date_pretty
1267
1268 (Future) Bill date as a human-readable string.  (Convenience for display;
1269 subject to change, so best not to parse for the date.)
1270
1271 =item amount
1272
1273 Base amount which will be charged if renewed early as of this date.
1274
1275 =item renew_date
1276
1277 Renewal date; i.e. even-futher future date at which the customer will be paid
1278 through if the early renewal is completed with the given B<bill-date>.
1279 Specified as a integer UNIX timestamp.
1280
1281 =item renew_date_pretty
1282
1283 Renewal date as a human-readable string.  (Convenience for display;
1284 subject to change, so best not to parse for the date.)
1285
1286 =item pkgnum
1287
1288 Package that will be renewed.
1289
1290 =item expire_date
1291
1292 Expiration date of the package that will be renewed.
1293
1294 =item expire_date_pretty
1295
1296 Expiration date of the package that will be renewed, as a human-readable
1297 string.  (Convenience for display; subject to change, so best not to parse for
1298 the date.)
1299
1300 =back
1301
1302 =item order_renew
1303
1304 Renews this customer early; i.e. runs billing for this customer in advance.
1305
1306 Takes a hash reference as parameter with the following keys:
1307
1308 =over 4
1309
1310 =item session_id
1311
1312 Session identifier
1313
1314 =item date
1315
1316 Integer date as returned by the B<renew_info> function, indicating the advance
1317 date for which to run billing.
1318
1319 =back
1320
1321 Returns a hash reference with a single key, B<error>, empty on success, or an
1322 error message on errors.
1323
1324 =item cancel_pkg
1325
1326 Cancels a package for this customer.
1327
1328 Takes a hash reference as parameter with the following keys:
1329
1330 =over 4
1331
1332 =item session_id
1333
1334 Session identifier
1335
1336 =item pkgpart
1337
1338 pkgpart of package to cancel
1339
1340 =back
1341
1342 Returns a hash reference with a single key, B<error>, empty on success, or an
1343 error message on errors.
1344
1345 =item provision_acct
1346
1347 Provisions an account (svc_acct).
1348
1349 Takes a hash reference as parameter with the following keys:
1350
1351 =over 4
1352
1353 =item session_id
1354
1355 Session identifier
1356
1357 =item pkgnum
1358
1359 pkgnum of package into which this service is provisioned
1360
1361 =item svcpart
1362
1363 svcpart or service definition to provision
1364
1365 =item username
1366
1367 =item domsvc
1368
1369 =item _password
1370
1371 =back
1372
1373 =item provision_phone
1374
1375 Provisions a phone number (svc_phone).
1376
1377 Takes a hash reference as parameter with the following keys:
1378
1379 =over 4
1380
1381 =item session_id
1382
1383 Session identifier
1384
1385 =item pkgnum
1386
1387 pkgnum of package into which this service is provisioned
1388
1389 =item svcpart
1390
1391 svcpart or service definition to provision
1392
1393 =item countrycode
1394
1395 =item phonenum
1396
1397 =item address1
1398
1399 =item address2
1400
1401 =item city
1402
1403 =item county
1404
1405 =item state
1406
1407 =item zip
1408
1409 =item country
1410
1411 E911 Address (optional)
1412
1413 =back
1414
1415 =item provision_pbx
1416
1417 Provisions a customer PBX (svc_pbx).
1418
1419 Takes a hash reference as parameter with the following keys:
1420
1421 =over 4
1422
1423 =item session_id
1424
1425 Session identifier
1426
1427 =item pkgnum
1428
1429 pkgnum of package into which this service is provisioned
1430
1431 =item svcpart
1432
1433 svcpart or service definition to provision
1434
1435 =item id
1436
1437 =item title
1438
1439 =item max_extensions
1440
1441 =item max_simultaneous
1442
1443 =item ip_addr
1444
1445 =back
1446
1447 =item provision_external
1448
1449 Provisions an external service (svc_external).
1450
1451 Takes a hash reference as parameter with the following keys:
1452
1453 =over 4
1454
1455 =item session_id
1456
1457 Session identifier
1458
1459 =item pkgnum
1460
1461 pkgnum of package into which this service is provisioned
1462
1463 =item svcpart
1464
1465 svcpart or service definition to provision
1466
1467 =item id
1468
1469 =item title
1470
1471 =back
1472
1473 =back
1474
1475 =head2 "MY ACCOUNT" CONTACT FUNCTIONS
1476
1477 =over 4
1478
1479 =item contact_passwd
1480
1481 Changes the password for the currently-logged in contact.
1482
1483 Takes a hash reference as parameter with the following keys:
1484
1485 =over 4
1486
1487 =item session_id
1488
1489 =item new_password
1490
1491 =back
1492
1493 Returns a hash reference with a single parameter, B<error>, which contains an
1494 error message, or empty on success.
1495
1496 =item list_contacts
1497
1498 Takes a hash reference as parameter with a single key, B<session_id>.
1499
1500 Returns a hash reference with two parameters: B<error>, which contains an error
1501 message, or empty on success, and B<contacts>, a list of contacts.
1502
1503 B<contacts> is an array reference of hash references (i.e. an array of structs,
1504  in XML-RPC).  Each hash reference (struct) has the following keys:
1505
1506 =over4
1507
1508 =item contactnum
1509
1510 =item class
1511
1512 Contact class name (contact type).
1513
1514 =item first
1515
1516 First name
1517
1518 =item last
1519
1520 Last name
1521
1522 =item title
1523
1524 Position ("Director of Silly Walks"), NOT honorific ("Mr." or "Mrs.")
1525
1526 =item emailaddress
1527
1528 Comma-separated list of email addresses
1529
1530 =item comment
1531
1532 =item selfservice_access
1533
1534 Y when enabled
1535
1536 =back
1537
1538 =item edit_contact
1539
1540 Updates information for the currently-logged in contact, or (optionally) the
1541 specified contact.
1542
1543 Takes a hash reference as parameter with the following keys:
1544
1545 =over 4
1546
1547 =item session_id
1548
1549 =item contactnum
1550
1551 If already logged in as a contact, this is optional.
1552
1553 =item first
1554
1555 =item last
1556
1557 =item emailaddress
1558
1559 =back
1560
1561 Returns a hash reference with a single parameter, B<error>, which contains an
1562 error message, or empty on success.
1563
1564 =item new_contact
1565
1566 Creates a new contact.
1567
1568 Takes a hash reference as parameter with the following keys:
1569
1570 =over 4
1571
1572 =item session_id
1573
1574 =item first
1575
1576 =item last
1577
1578 =item emailaddress
1579
1580 =item classnum
1581
1582 Optional contact classnum (TODO: or name)
1583
1584 =item comment
1585
1586 =item selfservice_access
1587
1588 Y to enable self-service access
1589
1590 =item _password
1591
1592 =back
1593
1594 Returns a hash reference with a single parameter, B<error>, which contains an
1595 error message, or empty on success.
1596
1597 =item delete_contact
1598
1599 Deletes a contact.  (Note: Cannot at this time delete the currently-logged in
1600 contact.)
1601
1602 Takes a hash reference as parameter with the following keys:
1603
1604 =over 4
1605
1606 =item session_id
1607
1608 =item contactnum
1609
1610 =back
1611
1612 Returns a hash reference with a single parameter, B<error>, which contains an
1613 error message, or empty on success.
1614
1615 =head2 "MY ACCOUNT" QUOTATION FUNCTIONS
1616
1617 All of these functions require the user to be logged in, and the 'session_id'
1618 key to be included in the argument hashref.`
1619
1620 =over 4
1621
1622 =item list_quotations HASHREF
1623
1624 Returns a hashref listing this customer's active self-service quotations.
1625 Contents are:
1626
1627 =over 4
1628
1629 =item quotations
1630
1631 an arrayref containing an element for each quotation.
1632
1633 =item quotationnum
1634
1635 the primary key
1636
1637 =item _date
1638
1639 the date it was started
1640
1641 =item num_pkgs
1642
1643 the number of packages
1644
1645 =item total_setup
1646
1647 the sum of setup fees
1648
1649 =item total_recur
1650
1651 the sum of recurring charges
1652
1653 =back
1654
1655 =item quotation_new HASHREF
1656
1657 Creates an empty quotation and returns a hashref containing 'quotationnum',
1658 the primary key of the new quotation.
1659
1660 =item quotation_delete HASHREF
1661
1662 Disables (does not really delete) a quotation. Takes the following arguments:
1663
1664 =over 4
1665
1666 =item session_id
1667
1668 =item quotationnum - the quotation to delete
1669
1670 =back
1671
1672 Returns 'error' => a string, which will be empty on success.
1673
1674 =item quotation_info HASHREF
1675
1676 Returns total and detailed pricing information on a quotation.
1677
1678 Takes the following arguments:
1679
1680 =over 4
1681
1682 =item session_id
1683
1684 =item quotationnum - the quotation to return
1685
1686 =back
1687
1688 Returns a hashref containing:
1689
1690 - total_setup, the total of setup fees (and their taxes)
1691 - total_recur, the total of all recurring charges (and their taxes)
1692 - sections, an arrayref containing an element for each quotation section.
1693   - description, a line of text describing the group of charges
1694   - subtotal, the total of charges in this group (if appropriate)
1695   - detail_items, an arrayref of line items
1696     - pkgnum, the reference number of the package
1697     - description, the package name (or tax name)
1698     - quantity
1699     - amount, the amount charged
1700     If the detail item represents a subtotal, it will instead contain:
1701     - total_item: description of the subtotal
1702     - total_amount: the subtotal amount
1703
1704
1705 =item quotation_print HASHREF
1706
1707 Renders the quotation as HTML or PDF. Takes the following arguments:
1708
1709 =over 4
1710
1711 =item session_id
1712
1713 =item quotationnum - the quotation to return
1714
1715 =item format - 'html' or 'pdf'
1716
1717 =back
1718
1719 Returns a hashref containing 'document', the contents of the file.
1720
1721 =item quotation_add_pkg HASHREF
1722
1723 Adds a package to a quotation. Takes the following arguments:
1724
1725 =over 4
1726
1727 =item session_id
1728
1729 =item pkgpart - the package to add
1730
1731 =item quotationnum - the quotation to add it to
1732
1733 =item quantity - the package quantity (defaults to 1)
1734
1735 =item address1, address2, city, state, zip, country - address fields to set
1736 the service location
1737
1738 =back
1739
1740 Returns 'error' => a string, which will be empty on success.
1741
1742 =item quotation_remove_pkg HASHREF
1743
1744 Removes a package from a quotation. Takes the following arguments:
1745
1746 =over 4
1747
1748 =item session_id
1749
1750 =item pkgnum - the primary key (quotationpkgnum) of the package to remove
1751
1752 =item quotationnum - the quotation to remove it from
1753
1754 =back
1755
1756 Returns 'error' => a string, which will be empty on success.
1757
1758 =back
1759
1760 =item quotation_order HASHREF
1761
1762 Converts the packages in a quotation into real packages. Takes the following
1763 arguments:
1764
1765 Takes the following arguments:
1766
1767 =over 4
1768
1769 =item session_id
1770
1771 =item quotationnum - the quotation to order
1772
1773 =back
1774
1775 =back
1776
1777 =head1 SIGNUP FUNCTIONS
1778
1779 =over 4
1780
1781 =item signup_info HASHREF
1782
1783 Takes a hash reference as parameter with the following keys:
1784
1785 =over 4
1786
1787 =item session_id - Optional agent/reseller interface session
1788
1789 =back
1790
1791 Returns a hash reference containing information that may be useful in
1792 displaying a signup page.  The hash reference contains the following keys:
1793
1794 =over 4
1795
1796 =item cust_main_county
1797
1798 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.
1799
1800 =item part_pkg
1801
1802 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
1803 an agentnum specified explicitly via reseller interface session_id in the
1804 options.
1805
1806 =item agent
1807
1808 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.
1809
1810 =item agentnum2part_pkg
1811
1812 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.
1813
1814 =item svc_acct_pop
1815
1816 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.
1817
1818 =item security_phrase
1819
1820 True if the "security_phrase" feature is enabled
1821
1822 =item payby
1823
1824 Array reference of acceptable payment types for signup
1825
1826 =over 4
1827
1828 =item CARD
1829
1830 credit card - automatic
1831
1832 =item DCRD
1833
1834 credit card - on-demand - version 1.5+ only
1835
1836 =item CHEK
1837
1838 electronic check - automatic
1839
1840 =item DCHK
1841
1842 electronic check - on-demand - version 1.5+ only
1843
1844 =item LECB
1845
1846 Phone bill billing
1847
1848 =item BILL
1849
1850 billing, not recommended for signups
1851
1852 =item COMP
1853
1854 free, definitely not recommended for signups
1855
1856 =item PREPAY
1857
1858 special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL
1859
1860 =back
1861
1862 =item cvv_enabled
1863
1864 True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch)
1865
1866 =item msgcat
1867
1868 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".
1869
1870 =item statedefault
1871
1872 Default state
1873
1874 =item countrydefault
1875
1876 Default country
1877
1878 =back
1879
1880 =item new_customer_minimal HASHREF
1881
1882 Creates a new customer.
1883
1884 Current differences from new_customer: An address is not required.  promo_code
1885 and reg_code are not supported.  If invoicing_list and _password is passed, a
1886 contact will be created with self-service access (no pkgpart or username is
1887 necessary).  No initial billing is run (this may change in a future version).
1888
1889 Takes a hash reference as parameter with the following keys:
1890
1891 =over 4
1892
1893 =item first
1894
1895 first name (required)
1896
1897 =item last
1898
1899 last name (required)
1900
1901 =item ss
1902
1903 (not typically collected; mostly used for ACH transactions)
1904
1905 =item company
1906
1907 Company name
1908
1909 =item address1
1910
1911 Address line one
1912
1913 =item address2
1914
1915 Address line two
1916
1917 =item city
1918
1919 City
1920
1921 =item county
1922
1923 County
1924
1925 =item state
1926
1927 State
1928
1929 =item zip
1930
1931 Zip or postal code
1932
1933 =item daytime
1934
1935 Daytime phone number
1936
1937 =item night
1938
1939 Evening phone number
1940
1941 =item fax
1942
1943 Fax number
1944
1945 =item payby
1946
1947 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L</signup_info> (required)
1948
1949 =item payinfo
1950
1951 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
1952
1953 =item paycvv
1954
1955 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
1956
1957 =item paydate
1958
1959 Expiration date for CARD/DCRD
1960
1961 =item payname
1962
1963 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
1964
1965 =item invoicing_list
1966
1967 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),
1968
1969 =item referral_custnum
1970
1971 referring customer number
1972
1973 =item agentnum
1974
1975 Agent number
1976
1977 =item pkgpart
1978
1979 pkgpart of initial package
1980
1981 =item username
1982
1983 Username
1984
1985 =item _password
1986
1987 Password
1988
1989 =item sec_phrase
1990
1991 Security phrase
1992
1993 =item popnum
1994
1995 Access number (index, not the literal number)
1996
1997 =item countrycode
1998
1999 Country code (to be provisioned as a service)
2000
2001 =item phonenum
2002
2003 Phone number (to be provisioned as a service)
2004
2005 =item pin
2006
2007 Voicemail PIN
2008
2009 =back
2010
2011 Returns a hash reference with the following keys:
2012
2013 =over 4
2014
2015 =item error
2016
2017 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)
2018
2019 =back
2020
2021 =item new_customer HASHREF
2022
2023 Creates a new customer.  Takes a hash reference as parameter with the
2024 following keys:
2025
2026 =over 4
2027
2028 =item first
2029
2030 first name (required)
2031
2032 =item last
2033
2034 last name (required)
2035
2036 =item ss
2037
2038 (not typically collected; mostly used for ACH transactions)
2039
2040 =item company
2041
2042 Company name
2043
2044 =item address1 (required)
2045
2046 Address line one
2047
2048 =item address2
2049
2050 Address line two
2051
2052 =item city (required)
2053
2054 City
2055
2056 =item county
2057
2058 County
2059
2060 =item state (required)
2061
2062 State
2063
2064 =item zip (required)
2065
2066 Zip or postal code
2067
2068 =item daytime
2069
2070 Daytime phone number
2071
2072 =item night
2073
2074 Evening phone number
2075
2076 =item fax
2077
2078 Fax number
2079
2080 =item payby
2081
2082 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L</signup_info> (required)
2083
2084 =item payinfo
2085
2086 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
2087
2088 =item paycvv
2089
2090 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
2091
2092 =item paydate
2093
2094 Expiration date for CARD/DCRD
2095
2096 =item payname
2097
2098 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
2099
2100 =item invoicing_list
2101
2102 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),
2103
2104 =item referral_custnum
2105
2106 referring customer number
2107
2108 =item agentnum
2109
2110 Agent number
2111
2112 =item pkgpart
2113
2114 pkgpart of initial package
2115
2116 =item username
2117
2118 Username
2119
2120 =item _password
2121
2122 Password
2123
2124 =item sec_phrase
2125
2126 Security phrase
2127
2128 =item popnum
2129
2130 Access number (index, not the literal number)
2131
2132 =item countrycode
2133
2134 Country code (to be provisioned as a service)
2135
2136 =item phonenum
2137
2138 Phone number (to be provisioned as a service)
2139
2140 =item pin
2141
2142 Voicemail PIN
2143
2144 =back
2145
2146 Returns a hash reference with the following keys:
2147
2148 =over 4
2149
2150 =item error
2151
2152 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)
2153
2154 =back
2155
2156 =item regionselector HASHREF | LIST
2157
2158 Takes as input a hashref or list of key/value pairs with the following keys:
2159
2160 =over 4
2161
2162 =item selected_county
2163
2164 Currently selected county
2165
2166 =item selected_state
2167
2168 Currently selected state
2169
2170 =item selected_country
2171
2172 Currently selected country
2173
2174 =item prefix
2175
2176 Specify a unique prefix string  if you intend to use the HTML output multiple time son one page.
2177
2178 =item onchange
2179
2180 Specify a javascript subroutine to call on changes
2181
2182 =item default_state
2183
2184 Default state
2185
2186 =item default_country
2187
2188 Default country
2189
2190 =item locales
2191
2192 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>.
2193
2194 =back
2195
2196 Returns a list consisting of three HTML fragments for county selection,
2197 state selection and country selection, respectively.
2198
2199 =cut
2200
2201 #false laziness w/FS::cust_main_county (this is currently the "newest" version)
2202 sub regionselector {
2203   my $param;
2204   if ( ref($_[0]) ) {
2205     $param = shift;
2206   } else {
2207     $param = { @_ };
2208   }
2209   $param->{'selected_country'} ||= $param->{'default_country'};
2210   $param->{'selected_state'} ||= $param->{'default_state'};
2211
2212   my $prefix = exists($param->{'prefix'}) ? $param->{'prefix'} : '';
2213
2214   my $countyflag = 0;
2215
2216   my %cust_main_county;
2217
2218 #  unless ( @cust_main_county ) { #cache
2219     #@cust_main_county = qsearch('cust_main_county', {} );
2220     #foreach my $c ( @cust_main_county ) {
2221     foreach my $c ( @{ $param->{'locales'} } ) {
2222       #$countyflag=1 if $c->county;
2223       $countyflag=1 if $c->{county};
2224       #push @{$cust_main_county{$c->country}{$c->state}}, $c->county;
2225       #$cust_main_county{$c->country}{$c->state}{$c->county} = 1;
2226       $cust_main_county{$c->{country}}{$c->{state}}{$c->{county}} = 1;
2227     }
2228 #  }
2229   $countyflag=1 if $param->{selected_county};
2230
2231   my $script_html = <<END;
2232     <SCRIPT>
2233     function opt(what,value,text) {
2234       var optionName = new Option(text, value, false, false);
2235       var length = what.length;
2236       what.options[length] = optionName;
2237     }
2238     function ${prefix}country_changed(what) {
2239       country = what.options[what.selectedIndex].text;
2240       for ( var i = what.form.${prefix}state.length; i >= 0; i-- )
2241           what.form.${prefix}state.options[i] = null;
2242 END
2243       #what.form.${prefix}state.options[0] = new Option('', '', false, true);
2244
2245   foreach my $country ( sort keys %cust_main_county ) {
2246     $script_html .= "\nif ( country == \"$country\" ) {\n";
2247     foreach my $state ( sort keys %{$cust_main_county{$country}} ) {
2248       my $text = $state || '(n/a)';
2249       $script_html .= qq!opt(what.form.${prefix}state, "$state", "$text");\n!;
2250     }
2251     $script_html .= "}\n";
2252   }
2253
2254   $script_html .= <<END;
2255     }
2256     function ${prefix}state_changed(what) {
2257 END
2258
2259   if ( $countyflag ) {
2260     $script_html .= <<END;
2261       state = what.options[what.selectedIndex].text;
2262       country = what.form.${prefix}country.options[what.form.${prefix}country.selectedIndex].text;
2263       for ( var i = what.form.${prefix}county.length; i >= 0; i-- )
2264           what.form.${prefix}county.options[i] = null;
2265 END
2266
2267     foreach my $country ( sort keys %cust_main_county ) {
2268       $script_html .= "\nif ( country == \"$country\" ) {\n";
2269       foreach my $state ( sort keys %{$cust_main_county{$country}} ) {
2270         $script_html .= "\nif ( state == \"$state\" ) {\n";
2271           #foreach my $county ( sort @{$cust_main_county{$country}{$state}} ) {
2272           foreach my $county ( sort keys %{$cust_main_county{$country}{$state}} ) {
2273             my $text = $county || '(n/a)';
2274             $script_html .=
2275               qq!opt(what.form.${prefix}county, "$county", "$text");\n!;
2276           }
2277         $script_html .= "}\n";
2278       }
2279       $script_html .= "}\n";
2280     }
2281   }
2282
2283   $script_html .= <<END;
2284     }
2285     </SCRIPT>
2286 END
2287
2288   my $county_html = $script_html;
2289   if ( $countyflag ) {
2290     $county_html .= qq!<SELECT NAME="${prefix}county" onChange="$param->{'onchange'}">!;
2291     foreach my $county (
2292       sort keys %{ $cust_main_county{$param->{'selected_country'}}{$param->{'selected_state'}} }
2293     ) {
2294       my $text = $county || '(n/a)';
2295       $county_html .= qq!<OPTION VALUE="$county"!.
2296                       ($county eq $param->{'selected_county'} ?
2297                         ' SELECTED>' :
2298                         '>'
2299                       ).
2300                       $text.
2301                       '</OPTION>';
2302     }
2303     $county_html .= '</SELECT>';
2304   } else {
2305     $county_html .=
2306       qq!<INPUT TYPE="hidden" NAME="${prefix}county" VALUE="$param->{'selected_county'}">!;
2307   }
2308
2309   my $state_html = qq!<SELECT NAME="${prefix}state" !.
2310                    qq!onChange="${prefix}state_changed(this); $param->{'onchange'}">!;
2311   foreach my $state ( sort keys %{ $cust_main_county{$param->{'selected_country'}} } ) {
2312     my $text = $state || '(n/a)';
2313     my $selected = $state eq $param->{'selected_state'} ? 'SELECTED' : '';
2314     $state_html .= "\n<OPTION $selected VALUE=\"$state\">$text</OPTION>"
2315   }
2316   $state_html .= '</SELECT>';
2317
2318   my $country_html = '';
2319   if ( scalar( keys %cust_main_county ) > 1 )  {
2320
2321     $country_html = qq(<SELECT NAME="${prefix}country" ).
2322                     qq(onChange="${prefix}country_changed(this); ).
2323                                  $param->{'onchange'}.
2324                                '"'.
2325                       '>';
2326     my $countrydefault = $param->{default_country} || 'US';
2327     foreach my $country (
2328       sort { ($b eq $countrydefault) <=> ($a eq $countrydefault) or $a cmp $b }
2329         keys %cust_main_county
2330     ) {
2331       my $selected = $country eq $param->{'selected_country'}
2332                        ? ' SELECTED'
2333                        : '';
2334       $country_html .= "\n<OPTION $selected>$country</OPTION>"
2335     }
2336     $country_html .= '</SELECT>';
2337   } else {
2338
2339     $country_html = qq(<INPUT TYPE="hidden" NAME="${prefix}country" ).
2340                             ' VALUE="'. (keys %cust_main_county )[0]. '">';
2341
2342   }
2343
2344   ($county_html, $state_html, $country_html);
2345
2346 }
2347
2348 sub regionselector_hashref {
2349   my ($county_html, $state_html, $country_html) = regionselector(@_);
2350   {
2351     'county_html'  => $county_html,
2352     'state_html'   => $state_html,
2353     'country_html' => $country_html,
2354   };
2355 }
2356
2357 =item location_form HASHREF | LIST
2358
2359 Takes as input a hashref or list of key/value pairs with the following keys:
2360
2361 =over 4
2362
2363 =item session_id
2364
2365 Current customer session_id
2366
2367 =item no_asterisks
2368
2369 Omit red asterisks from required fields.
2370
2371 =item address1_label
2372
2373 Label for first address line.
2374
2375 =back
2376
2377 Returns an HTML fragment for a location form (address, city, state, zip,
2378 country)
2379
2380 =cut
2381
2382 sub location_form {
2383   my $param;
2384   if ( ref($_[0]) ) {
2385     $param = shift;
2386   } else {
2387     $param = { @_ };
2388   }
2389
2390   my $session_id = delete $param->{'session_id'};
2391
2392   my $rv = mason_comp( 'session_id' => $session_id,
2393                        'comp'       => '/elements/location.html',
2394                        'args'       => [ %$param ],
2395                      );
2396
2397   #hmm.
2398   $rv->{'error'} || $rv->{'output'};
2399
2400 }
2401
2402
2403 #=item expselect HASHREF | LIST
2404 #
2405 #Takes as input a hashref or list of key/value pairs with the following keys:
2406 #
2407 #=over 4
2408 #
2409 #=item prefix - Specify a unique prefix string  if you intend to use the HTML output multiple time son one page.
2410 #
2411 #=item date - current date, in yyyy-mm-dd or m-d-yyyy format
2412 #
2413 #=back
2414
2415 =item expselect PREFIX [ DATE ]
2416
2417 Takes as input a unique prefix string and the current expiration date, in
2418 yyyy-mm-dd or m-d-yyyy format
2419
2420 Returns an HTML fragments for expiration date selection.
2421
2422 =cut
2423
2424 sub expselect {
2425   #my $param;
2426   #if ( ref($_[0]) ) {
2427   #  $param = shift;
2428   #} else {
2429   #  $param = { @_ };
2430   #my $prefix = $param->{'prefix'};
2431   #my $prefix = exists($param->{'prefix'}) ? $param->{'prefix'} : '';
2432   #my $date =   exists($param->{'date'})   ? $param->{'date'}   : '';
2433   my $prefix = shift;
2434   my $date = scalar(@_) ? shift : '';
2435
2436   my( $m, $y ) = ( 0, 0 );
2437   if ( $date  =~ /^(\d{4})-(\d{2})-\d{2}$/ ) { #PostgreSQL date format
2438     ( $m, $y ) = ( $2, $1 );
2439   } elsif ( $date =~ /^(\d{1,2})-(\d{1,2}-)?(\d{4}$)/ ) {
2440     ( $m, $y ) = ( $1, $3 );
2441   }
2442   my $return = qq!<SELECT NAME="$prefix!. qq!_month" SIZE="1">!;
2443   for ( 1 .. 12 ) {
2444     $return .= qq!<OPTION VALUE="$_"!;
2445     $return .= " SELECTED" if $_ == $m;
2446     $return .= ">$_";
2447   }
2448   $return .= qq!</SELECT>/<SELECT NAME="$prefix!. qq!_year" SIZE="1">!;
2449   my @t = localtime;
2450   my $thisYear = $t[5] + 1900;
2451   for ( ($thisYear > $y && $y > 0 ? $y : $thisYear) .. ($thisYear+10) ) {
2452     $return .= qq!<OPTION VALUE="$_"!;
2453     $return .= " SELECTED" if $_ == $y;
2454     $return .= ">$_";
2455   }
2456   $return .= "</SELECT>";
2457
2458   $return;
2459 }
2460
2461 =item popselector HASHREF | LIST
2462
2463 Takes as input a hashref or list of key/value pairs with the following keys:
2464
2465 =over 4
2466
2467 =item popnum
2468
2469 Access number number
2470
2471 =item pops
2472
2473 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>.
2474
2475 =back
2476
2477 Returns an HTML fragment for access number selection.
2478
2479 =cut
2480
2481 #horrible false laziness with FS/FS/svc_acct_pop.pm::popselector
2482 sub popselector {
2483   my $param;
2484   if ( ref($_[0]) ) {
2485     $param = shift;
2486   } else {
2487     $param = { @_ };
2488   }
2489   my $popnum = $param->{'popnum'};
2490   my $pops = $param->{'pops'};
2491
2492   return '<INPUT TYPE="hidden" NAME="popnum" VALUE="">' unless @$pops;
2493   return $pops->[0]{city}. ', '. $pops->[0]{state}.
2494          ' ('. $pops->[0]{ac}. ')/'. $pops->[0]{exch}. '-'. $pops->[0]{loc}.
2495          '<INPUT TYPE="hidden" NAME="popnum" VALUE="'. $pops->[0]{popnum}. '">'
2496     if scalar(@$pops) == 1;
2497
2498   my %pop = ();
2499   my %popnum2pop = ();
2500   foreach (@$pops) {
2501     push @{ $pop{ $_->{state} }->{ $_->{ac} } }, $_;
2502     $popnum2pop{$_->{popnum}} = $_;
2503   }
2504
2505   my $text = <<END;
2506     <SCRIPT>
2507     function opt(what,href,text) {
2508       var optionName = new Option(text, href, false, false)
2509       var length = what.length;
2510       what.options[length] = optionName;
2511     }
2512 END
2513
2514   my $init_popstate = $param->{'init_popstate'};
2515   if ( $init_popstate ) {
2516     $text .= '<INPUT TYPE="hidden" NAME="init_popstate" VALUE="'.
2517              $init_popstate. '">';
2518   } else {
2519     $text .= <<END;
2520       function acstate_changed(what) {
2521         state = what.options[what.selectedIndex].text;
2522         what.form.popac.options.length = 0
2523         what.form.popac.options[0] = new Option("Area code", "-1", false, true);
2524 END
2525   }
2526
2527   my @states = $init_popstate ? ( $init_popstate ) : keys %pop;
2528   foreach my $state ( sort { $a cmp $b } @states ) {
2529     $text .= "\nif ( state == \"$state\" ) {\n" unless $init_popstate;
2530
2531     foreach my $ac ( sort { $a cmp $b } keys %{ $pop{$state} }) {
2532       $text .= "opt(what.form.popac, \"$ac\", \"$ac\");\n";
2533       if ($ac eq $param->{'popac'}) {
2534         $text .= "what.form.popac.options[what.form.popac.length-1].selected = true;\n";
2535       }
2536     }
2537     $text .= "}\n" unless $init_popstate;
2538   }
2539   $text .= "popac_changed(what.form.popac)}\n";
2540
2541   $text .= <<END;
2542   function popac_changed(what) {
2543     ac = what.options[what.selectedIndex].text;
2544     what.form.popnum.options.length = 0;
2545     what.form.popnum.options[0] = new Option("City", "-1", false, true);
2546
2547 END
2548
2549   foreach my $state ( @states ) {
2550     foreach my $popac ( keys %{ $pop{$state} } ) {
2551       $text .= "\nif ( ac == \"$popac\" ) {\n";
2552
2553       foreach my $pop ( @{$pop{$state}->{$popac}}) {
2554         my $o_popnum = $pop->{popnum};
2555         my $poptext =  $pop->{city}. ', '. $pop->{state}.
2556                        ' ('. $pop->{ac}. ')/'. $pop->{exch}. '-'. $pop->{loc};
2557
2558         $text .= "opt(what.form.popnum, \"$o_popnum\", \"$poptext\");\n";
2559         if ($popnum == $o_popnum) {
2560           $text .= "what.form.popnum.options[what.form.popnum.length-1].selected = true;\n";
2561         }
2562       }
2563       $text .= "}\n";
2564     }
2565   }
2566
2567
2568   $text .= "}\n</SCRIPT>\n";
2569
2570   $param->{'acstate'} = '' unless defined($param->{'acstate'});
2571
2572   $text .=
2573     qq!<TABLE CELLPADDING="0"><TR><TD><SELECT NAME="acstate"! .
2574     qq!SIZE=1 onChange="acstate_changed(this)"><OPTION VALUE=-1>State!;
2575   $text .= "<OPTION" . ($_ eq $param->{'acstate'} ? " SELECTED" : "") .
2576            ">$_" foreach sort { $a cmp $b } @states;
2577   $text .= '</SELECT>'; #callback? return 3 html pieces?  #'</TD>';
2578
2579   $text .=
2580     qq!<SELECT NAME="popac" SIZE=1 onChange="popac_changed(this)">!.
2581     qq!<OPTION>Area code</SELECT></TR><TR VALIGN="top">!;
2582
2583   $text .= qq!<TR><TD><SELECT NAME="popnum" SIZE=1 STYLE="width: 20em"><OPTION>City!;
2584
2585
2586   #comment this block to disable initial list polulation
2587   my @initial_select = ();
2588   if ( scalar( @$pops ) > 100 ) {
2589     push @initial_select, $popnum2pop{$popnum} if $popnum2pop{$popnum};
2590   } else {
2591     @initial_select = @$pops;
2592   }
2593   foreach my $pop ( sort { $a->{state} cmp $b->{state} } @initial_select ) {
2594     $text .= qq!<OPTION VALUE="!. $pop->{popnum}. '"'.
2595              ( ( $popnum && $pop->{popnum} == $popnum ) ? ' SELECTED' : '' ). ">".
2596              $pop->{city}. ', '. $pop->{state}.
2597                ' ('. $pop->{ac}. ')/'. $pop->{exch}. '-'. $pop->{loc};
2598   }
2599
2600   $text .= qq!</SELECT></TD></TR></TABLE>!;
2601
2602   $text;
2603
2604 }
2605
2606 =item domainselector HASHREF | LIST
2607
2608 Takes as input a hashref or list of key/value pairs with the following keys:
2609
2610 =over 4
2611
2612 =item pkgnum
2613
2614 Package number
2615
2616 =item domsvc
2617
2618 Service number of the selected item.
2619
2620 =back
2621
2622 Returns an HTML fragment for domain selection.
2623
2624 =cut
2625
2626 sub domainselector {
2627   my $param;
2628   if ( ref($_[0]) ) {
2629     $param = shift;
2630   } else {
2631     $param = { @_ };
2632   }
2633   my $domsvc= $param->{'domsvc'};
2634   my $rv =
2635       domain_select_hash(map {$_ => $param->{$_}} qw(pkgnum svcpart pkgpart) );
2636   my $domains = $rv->{'domains'};
2637   $domsvc = $rv->{'domsvc'} unless $domsvc;
2638
2639   return '<INPUT TYPE="hidden" NAME="domsvc" VALUE="">'
2640     unless scalar(keys %$domains);
2641
2642   if (scalar(keys %$domains) == 1) {
2643     my $key;
2644     foreach(keys %$domains) {
2645       $key = $_;
2646     }
2647     return '<TR><TD ALIGN="right">Domain</TD><TD>'. $domains->{$key}.
2648            '<INPUT TYPE="hidden" NAME="domsvc" VALUE="'. $key. '"></TD></TR>'
2649   }
2650
2651   my $text .= qq!<TR><TD ALIGN="right">Domain</TD><TD><SELECT NAME="domsvc" SIZE=1 STYLE="width: 20em">!;
2652
2653   $text .= '<OPTION>(Choose Domain)' unless $domsvc;
2654
2655   foreach my $domain ( sort { $domains->{$a} cmp $domains->{$b} } keys %$domains ) {
2656     $text .= qq!<OPTION VALUE="!. $domain. '"'.
2657              ( ( $domsvc && $domain == $domsvc ) ? ' SELECTED' : '' ). ">".
2658              $domains->{$domain};
2659   }
2660
2661   $text .= qq!</SELECT></TD></TR>!;
2662
2663   $text;
2664
2665 }
2666
2667 =item didselector HASHREF | LIST
2668
2669 Takes as input a hashref or list of key/value pairs with the following keys:
2670
2671 =over 4
2672
2673 =item field
2674
2675 Field name for the returned HTML fragment.
2676
2677 =item svcpart
2678
2679 Service definition (see L<FS::part_svc>)
2680
2681 =back
2682
2683 Returns an HTML fragment for DID selection.
2684
2685 =cut
2686
2687 sub didselector {
2688   my $param;
2689   if ( ref($_[0]) ) {
2690     $param = shift;
2691   } else {
2692     $param = { @_ };
2693   }
2694
2695   my $rv = mason_comp( 'comp'=>'/elements/select-did.html',
2696                        'args'=>[ %$param ],
2697                      );
2698
2699   #hmm.
2700   $rv->{'error'} || $rv->{'output'};
2701
2702 }
2703
2704 =back
2705
2706 =head1 RESELLER FUNCTIONS
2707
2708 Note: Resellers can also use the B<signup_info> and B<new_customer> functions
2709 with their active session, and the B<customer_info> and B<order_pkg> functions
2710 with their active session and an additional I<custnum> parameter.
2711
2712 For the most part, development of the reseller web interface has been
2713 superceded by agent-virtualized access to the backend.
2714
2715 =over 4
2716
2717 =item agent_login
2718
2719 Agent login
2720
2721 =item agent_info
2722
2723 Agent info
2724
2725 =item agent_list_customers
2726
2727 List agent's customers.
2728
2729 =back
2730
2731 =head1 BUGS
2732
2733 =head1 SEE ALSO
2734
2735 L<freeside-selfservice-clientd>, L<freeside-selfservice-server>
2736
2737 =cut
2738
2739 1;
2740