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