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 (None of this is required at all if you are just ordering a package
1098 at the customer's existing default service location.)
1099
1100 =item address1
1101
1102 =item address2
1103
1104 =item city
1105
1106 =item county
1107
1108 =item state
1109
1110 =item zip
1111
1112 =item country
1113
1114 =item svcpart
1115
1116 Service to order (see L<FS::part_svc>).
1117
1118 Normally optional; required only to provision a non-svc_acct service, or if the
1119 package definition does not contain one svc_acct service definition with
1120 quantity 1 (it may contain others with quantity >1).  A svcpart of "none" can
1121 also be specified to indicate that no initial service should be provisioned.
1122
1123 =back
1124
1125 Fields used when provisioning an svc_acct service:
1126
1127 =over 4
1128
1129 =item username
1130
1131 Username
1132
1133 =item _password
1134
1135 Password
1136
1137 =item sec_phrase
1138
1139 Optional security phrase
1140
1141 =item popnum
1142
1143 Optional Access number number
1144
1145 =back
1146
1147 Fields used when provisioning an svc_domain service:
1148
1149 =over 4
1150
1151 =item domain
1152
1153 Domain
1154
1155 =back
1156
1157 Fields used when provisioning an svc_phone service:
1158
1159 =over 4
1160
1161 =item phonenum
1162
1163 Phone number
1164
1165 =item pin
1166
1167 Voicemail PIN
1168
1169 =item sip_password
1170
1171 SIP password
1172
1173 =back
1174
1175 Fields used when provisioning an svc_external service:
1176
1177 =over 4
1178
1179 =item id
1180
1181 External numeric ID.
1182
1183 =item title
1184
1185 External text title.
1186
1187 =back
1188
1189 Fields used when provisioning an svc_pbx service:
1190
1191 =over 4
1192
1193 =item id
1194
1195 Numeric ID.
1196
1197 =item name
1198
1199 Text name.
1200
1201 =back
1202
1203 Returns a hash reference with a single key, B<error>, empty on success, or an
1204 error message on errors.  The special error '_decline' is returned for
1205 declined transactions.
1206
1207 =item change_pkg
1208
1209 Changes a package for this customer.
1210
1211 Takes a hash reference as parameter with the following keys:
1212
1213 =over 4
1214
1215 =item session_id
1216
1217 Session identifier
1218
1219 =item pkgnum
1220
1221 Existing customer package.
1222
1223 =item pkgpart
1224
1225 New package to order (see L<FS::part_pkg>).
1226
1227 =item quantity
1228
1229 Quantity for this package order (default 1).
1230
1231 =back
1232
1233 Returns a hash reference with the following keys:
1234
1235 =over 4
1236
1237 =item error
1238
1239 Empty on success, or an error message on errors.
1240
1241 =item pkgnum
1242
1243 On success, the new pkgnum
1244
1245 =back
1246
1247
1248 =item renew_info
1249
1250 Provides useful info for early renewals.
1251
1252 Takes a hash reference as parameter with the following keys:
1253
1254 =over 4
1255
1256 =item session_id
1257
1258 Session identifier
1259
1260 =back
1261
1262 Returns a hash reference.  On errors, it contains a single key, B<error>, with
1263 the error message.  Otherwise, contains a single key, B<dates>, pointing to
1264 an array refernce of hash references.  Each hash reference contains the
1265 following keys:
1266
1267 =over 4
1268
1269 =item bill_date
1270
1271 (Future) Bill date.  Indicates a future date for which billing could be run.
1272 Specified as an integer UNIX timestamp.  Pass this value to the B<order_renew>
1273 function.
1274
1275 =item bill_date_pretty
1276
1277 (Future) Bill date as a human-readable string.  (Convenience for display;
1278 subject to change, so best not to parse for the date.)
1279
1280 =item amount
1281
1282 Base amount which will be charged if renewed early as of this date.
1283
1284 =item renew_date
1285
1286 Renewal date; i.e. even-futher future date at which the customer will be paid
1287 through if the early renewal is completed with the given B<bill-date>.
1288 Specified as an integer UNIX timestamp.
1289
1290 =item renew_date_pretty
1291
1292 Renewal date as a human-readable string.  (Convenience for display;
1293 subject to change, so best not to parse for the date.)
1294
1295 =item pkgnum
1296
1297 Package that will be renewed.
1298
1299 =item expire_date
1300
1301 Expiration date of the package that will be renewed.
1302
1303 =item expire_date_pretty
1304
1305 Expiration date of the package that will be renewed, as a human-readable
1306 string.  (Convenience for display; subject to change, so best not to parse for
1307 the date.)
1308
1309 =back
1310
1311 =item order_renew
1312
1313 Renews this customer early; i.e. runs billing for this customer in advance.
1314
1315 Takes a hash reference as parameter with the following keys:
1316
1317 =over 4
1318
1319 =item session_id
1320
1321 Session identifier
1322
1323 =item date
1324
1325 Integer date as returned by the B<renew_info> function, indicating the advance
1326 date for which to run billing.
1327
1328 =back
1329
1330 Returns a hash reference with a single key, B<error>, empty on success, or an
1331 error message on errors.
1332
1333 =item cancel_pkg
1334
1335 Cancels a package for this customer.
1336
1337 Takes a hash reference as parameter with the following keys:
1338
1339 =over 4
1340
1341 =item session_id
1342
1343 Session identifier
1344
1345 =item pkgpart
1346
1347 pkgpart of package to cancel
1348
1349 =item date
1350
1351 Optional date, for future cancellation (expiration) instead of immediate
1352 cancellation.  Specified as an integer UNIX timestamp ("epoch time").
1353
1354 =back
1355
1356 Returns a hash reference with a single key, B<error>, empty on success, or an
1357 error message on errors.
1358
1359 =item provision_acct
1360
1361 Provisions an account (svc_acct).
1362
1363 Takes a hash reference as parameter with the following keys:
1364
1365 =over 4
1366
1367 =item session_id
1368
1369 Session identifier
1370
1371 =item pkgnum
1372
1373 pkgnum of package into which this service is provisioned
1374
1375 =item svcpart
1376
1377 svcpart or service definition to provision
1378
1379 =item username
1380
1381 =item domsvc
1382
1383 =item _password
1384
1385 =back
1386
1387 =item provision_phone
1388
1389 Provisions a phone number (svc_phone).
1390
1391 Takes a hash reference as parameter with the following keys:
1392
1393 =over 4
1394
1395 =item session_id
1396
1397 Session identifier
1398
1399 =item pkgnum
1400
1401 pkgnum of package into which this service is provisioned
1402
1403 =item svcpart
1404
1405 svcpart or service definition to provision
1406
1407 =item countrycode
1408
1409 =item phonenum
1410
1411 =item address1
1412
1413 =item address2
1414
1415 =item city
1416
1417 =item county
1418
1419 =item state
1420
1421 =item zip
1422
1423 =item country
1424
1425 E911 Address (optional)
1426
1427 =back
1428
1429 =item provision_pbx
1430
1431 Provisions a customer PBX (svc_pbx).
1432
1433 Takes a hash reference as parameter with the following keys:
1434
1435 =over 4
1436
1437 =item session_id
1438
1439 Session identifier
1440
1441 =item pkgnum
1442
1443 pkgnum of package into which this service is provisioned
1444
1445 =item svcpart
1446
1447 svcpart or service definition to provision
1448
1449 =item id
1450
1451 =item title
1452
1453 =item max_extensions
1454
1455 =item max_simultaneous
1456
1457 =item ip_addr
1458
1459 =back
1460
1461 =item provision_external
1462
1463 Provisions an external service (svc_external).
1464
1465 Takes a hash reference as parameter with the following keys:
1466
1467 =over 4
1468
1469 =item session_id
1470
1471 Session identifier
1472
1473 =item pkgnum
1474
1475 pkgnum of package into which this service is provisioned
1476
1477 =item svcpart
1478
1479 svcpart or service definition to provision
1480
1481 =item id
1482
1483 =item title
1484
1485 =back
1486
1487 =back
1488
1489 =head2 "MY ACCOUNT" CONTACT FUNCTIONS
1490
1491 =over 4
1492
1493 =item contact_passwd
1494
1495 Changes the password for the currently-logged in contact.
1496
1497 Takes a hash reference as parameter with the following keys:
1498
1499 =over 4
1500
1501 =item session_id
1502
1503 =item new_password
1504
1505 =back
1506
1507 Returns a hash reference with a single parameter, B<error>, which contains an
1508 error message, or empty on success.
1509
1510 =item list_contacts
1511
1512 Takes a hash reference as parameter with a single key, B<session_id>.
1513
1514 Returns a hash reference with two parameters: B<error>, which contains an error
1515 message, or empty on success, and B<contacts>, a list of contacts.
1516
1517 B<contacts> is an array reference of hash references (i.e. an array of structs,
1518  in XML-RPC).  Each hash reference (struct) has the following keys:
1519
1520 =over 4
1521
1522 =item contactnum
1523
1524 =item class
1525
1526 Contact class name (contact type).
1527
1528 =item first
1529
1530 First name
1531
1532 =item last
1533
1534 Last name
1535
1536 =item title
1537
1538 Position ("Director of Silly Walks"), NOT honorific ("Mr." or "Mrs.")
1539
1540 =item emailaddress
1541
1542 Comma-separated list of email addresses
1543
1544 =item comment
1545
1546 =item selfservice_access
1547
1548 Y when enabled
1549
1550 =back
1551
1552 =item edit_contact
1553
1554 Updates information for the currently-logged in contact, or (optionally) the
1555 specified contact.
1556
1557 Takes a hash reference as parameter with the following keys:
1558
1559 =over 4
1560
1561 =item session_id
1562
1563 =item contactnum
1564
1565 If already logged in as a contact, this is optional.
1566
1567 =item first
1568
1569 =item last
1570
1571 =item emailaddress
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 =item new_contact
1579
1580 Creates a new contact.
1581
1582 Takes a hash reference as parameter with the following keys:
1583
1584 =over 4
1585
1586 =item session_id
1587
1588 =item first
1589
1590 =item last
1591
1592 =item emailaddress
1593
1594 =item classnum
1595
1596 Optional contact classnum (TODO: or name)
1597
1598 =item comment
1599
1600 =item selfservice_access
1601
1602 Y to enable self-service access
1603
1604 =item _password
1605
1606 =back
1607
1608 Returns a hash reference with a single parameter, B<error>, which contains an
1609 error message, or empty on success.
1610
1611 =item delete_contact
1612
1613 Deletes a contact.  (Note: Cannot at this time delete the currently-logged in
1614 contact.)
1615
1616 Takes a hash reference as parameter with the following keys:
1617
1618 =over 4
1619
1620 =item session_id
1621
1622 =item contactnum
1623
1624 =back
1625
1626 Returns a hash reference with a single parameter, B<error>, which contains an
1627 error message, or empty on success.
1628
1629 =back
1630
1631 =head2 "MY ACCOUNT" QUOTATION FUNCTIONS
1632
1633 All of these functions require the user to be logged in, and the 'session_id'
1634 key to be included in the argument hashref.`
1635
1636 =over 4
1637
1638 =item list_quotations HASHREF
1639
1640 Returns a hashref listing this customer's active self-service quotations.
1641 Contents are:
1642
1643 =over 4
1644
1645 =item quotations
1646
1647 an arrayref containing an element for each quotation.
1648
1649 =item quotationnum
1650
1651 the primary key
1652
1653 =item _date
1654
1655 the date it was started
1656
1657 =item num_pkgs
1658
1659 the number of packages
1660
1661 =item total_setup
1662
1663 the sum of setup fees
1664
1665 =item total_recur
1666
1667 the sum of recurring charges
1668
1669 =back
1670
1671 =item quotation_new HASHREF
1672
1673 Creates an empty quotation and returns a hashref containing 'quotationnum',
1674 the primary key of the new quotation.
1675
1676 =item quotation_delete HASHREF
1677
1678 Disables (does not really delete) a quotation. Takes the following arguments:
1679
1680 =over 4
1681
1682 =item session_id
1683
1684 =item quotationnum - the quotation to delete
1685
1686 =back
1687
1688 Returns 'error' => a string, which will be empty on success.
1689
1690 =item quotation_info HASHREF
1691
1692 Returns total and detailed pricing information on a quotation.
1693
1694 Takes the following arguments:
1695
1696 =over 4
1697
1698 =item session_id
1699
1700 =item quotationnum - the quotation to return
1701
1702 =back
1703
1704 Returns a hashref containing:
1705
1706 - total_setup, the total of setup fees (and their taxes)
1707 - total_recur, the total of all recurring charges (and their taxes)
1708 - sections, an arrayref containing an element for each quotation section.
1709   - description, a line of text describing the group of charges
1710   - subtotal, the total of charges in this group (if appropriate)
1711   - detail_items, an arrayref of line items
1712     - pkgnum, the reference number of the package
1713     - description, the package name (or tax name)
1714     - quantity
1715     - amount, the amount charged
1716     If the detail item represents a subtotal, it will instead contain:
1717     - total_item: description of the subtotal
1718     - total_amount: the subtotal amount
1719
1720
1721 =item quotation_print HASHREF
1722
1723 Renders the quotation as HTML or PDF. Takes the following arguments:
1724
1725 =over 4
1726
1727 =item session_id
1728
1729 =item quotationnum - the quotation to return
1730
1731 =item format - 'html' or 'pdf'
1732
1733 =back
1734
1735 Returns a hashref containing 'document', the contents of the file.
1736
1737 =item quotation_add_pkg HASHREF
1738
1739 Adds a package to a quotation. Takes the following arguments:
1740
1741 =over 4
1742
1743 =item session_id
1744
1745 =item pkgpart - the package to add
1746
1747 =item quotationnum - the quotation to add it to
1748
1749 =item quantity - the package quantity (defaults to 1)
1750
1751 =item address1, address2, city, state, zip, country - address fields to set
1752 the service location
1753
1754 =back
1755
1756 Returns 'error' => a string, which will be empty on success.
1757
1758 =item quotation_remove_pkg HASHREF
1759
1760 Removes a package from a quotation. Takes the following arguments:
1761
1762 =over 4
1763
1764 =item session_id
1765
1766 =item pkgnum - the primary key (quotationpkgnum) of the package to remove
1767
1768 =item quotationnum - the quotation to remove it from
1769
1770 =back
1771
1772 Returns 'error' => a string, which will be empty on success.
1773
1774 =item quotation_order HASHREF
1775
1776 Converts the packages in a quotation into real packages. Takes the following
1777 arguments:
1778
1779 Takes the following arguments:
1780
1781 =over 4
1782
1783 =item session_id
1784
1785 =item quotationnum - the quotation to order
1786
1787 =back
1788
1789 =back
1790
1791 =head1 SIGNUP FUNCTIONS
1792
1793 =over 4
1794
1795 =item signup_info HASHREF
1796
1797 Takes a hash reference as parameter with the following keys:
1798
1799 =over 4
1800
1801 =item session_id - Optional agent/reseller interface session
1802
1803 =back
1804
1805 Returns a hash reference containing information that may be useful in
1806 displaying a signup page.  The hash reference contains the following keys:
1807
1808 =over 4
1809
1810 =item cust_main_county
1811
1812 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.
1813
1814 =item part_pkg
1815
1816 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
1817 an agentnum specified explicitly via reseller interface session_id in the
1818 options.
1819
1820 =item agent
1821
1822 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.
1823
1824 =item agentnum2part_pkg
1825
1826 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.
1827
1828 =item svc_acct_pop
1829
1830 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.
1831
1832 =item security_phrase
1833
1834 True if the "security_phrase" feature is enabled
1835
1836 =item payby
1837
1838 Array reference of acceptable payment types for signup
1839
1840 =over 4
1841
1842 =item CARD
1843
1844 credit card - automatic
1845
1846 =item DCRD
1847
1848 credit card - on-demand - version 1.5+ only
1849
1850 =item CHEK
1851
1852 electronic check - automatic
1853
1854 =item DCHK
1855
1856 electronic check - on-demand - version 1.5+ only
1857
1858 =item LECB
1859
1860 Phone bill billing
1861
1862 =item BILL
1863
1864 billing, not recommended for signups
1865
1866 =item COMP
1867
1868 free, definitely not recommended for signups
1869
1870 =item PREPAY
1871
1872 special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL
1873
1874 =back
1875
1876 =item cvv_enabled
1877
1878 True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch)
1879
1880 =item msgcat
1881
1882 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".
1883
1884 =item statedefault
1885
1886 Default state
1887
1888 =item countrydefault
1889
1890 Default country
1891
1892 =back
1893
1894 =item new_customer_minimal HASHREF
1895
1896 Creates a new customer.
1897
1898 Current differences from new_customer: An address is not required.  promo_code
1899 and reg_code are not supported.  If invoicing_list and _password is passed, a
1900 contact will be created with self-service access (no pkgpart or username is
1901 necessary).  No initial billing is run (this may change in a future version).
1902
1903 Takes a hash reference as parameter with the following keys:
1904
1905 =over 4
1906
1907 =item first
1908
1909 first name (required)
1910
1911 =item last
1912
1913 last name (required)
1914
1915 =item ss
1916
1917 (not typically collected; mostly used for ACH transactions)
1918
1919 =item company
1920
1921 Company name
1922
1923 =item address1
1924
1925 Address line one
1926
1927 =item address2
1928
1929 Address line two
1930
1931 =item city
1932
1933 City
1934
1935 =item county
1936
1937 County
1938
1939 =item state
1940
1941 State
1942
1943 =item zip
1944
1945 Zip or postal code
1946
1947 =item daytime
1948
1949 Daytime phone number
1950
1951 =item night
1952
1953 Evening phone number
1954
1955 =item fax
1956
1957 Fax number
1958
1959 =item payby
1960
1961 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L</signup_info> (required)
1962
1963 =item payinfo
1964
1965 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
1966
1967 =item paycvv
1968
1969 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
1970
1971 =item paydate
1972
1973 Expiration date for CARD/DCRD
1974
1975 =item payname
1976
1977 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
1978
1979 =item invoicing_list
1980
1981 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),
1982
1983 =item referral_custnum
1984
1985 referring customer number
1986
1987 =item agentnum
1988
1989 Agent number
1990
1991 =item pkgpart
1992
1993 pkgpart of initial package
1994
1995 =item username
1996
1997 Username
1998
1999 =item _password
2000
2001 Password
2002
2003 =item sec_phrase
2004
2005 Security phrase
2006
2007 =item popnum
2008
2009 Access number (index, not the literal number)
2010
2011 =item countrycode
2012
2013 Country code (to be provisioned as a service)
2014
2015 =item phonenum
2016
2017 Phone number (to be provisioned as a service)
2018
2019 =item pin
2020
2021 Voicemail PIN
2022
2023 =back
2024
2025 Returns a hash reference with the following keys:
2026
2027 =over 4
2028
2029 =item error
2030
2031 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)
2032
2033 =back
2034
2035 =item new_customer HASHREF
2036
2037 Creates a new customer.  Takes a hash reference as parameter with the
2038 following keys:
2039
2040 =over 4
2041
2042 =item first
2043
2044 first name (required)
2045
2046 =item last
2047
2048 last name (required)
2049
2050 =item ss
2051
2052 (not typically collected; mostly used for ACH transactions)
2053
2054 =item company
2055
2056 Company name
2057
2058 =item address1 (required)
2059
2060 Address line one
2061
2062 =item address2
2063
2064 Address line two
2065
2066 =item city (required)
2067
2068 City
2069
2070 =item county
2071
2072 County
2073
2074 =item state (required)
2075
2076 State
2077
2078 =item zip (required)
2079
2080 Zip or postal code
2081
2082 =item daytime
2083
2084 Daytime phone number
2085
2086 =item night
2087
2088 Evening phone number
2089
2090 =item fax
2091
2092 Fax number
2093
2094 =item payby
2095
2096 CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L</signup_info> (required)
2097
2098 =item payinfo
2099
2100 Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
2101
2102 =item paycvv
2103
2104 Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
2105
2106 =item paydate
2107
2108 Expiration date for CARD/DCRD
2109
2110 =item payname
2111
2112 Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
2113
2114 =item invoicing_list
2115
2116 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),
2117
2118 =item referral_custnum
2119
2120 referring customer number
2121
2122 =item agentnum
2123
2124 Agent number
2125
2126 =item pkgpart
2127
2128 pkgpart of initial package
2129
2130 =item username
2131
2132 Username
2133
2134 =item _password
2135
2136 Password
2137
2138 =item sec_phrase
2139
2140 Security phrase
2141
2142 =item popnum
2143
2144 Access number (index, not the literal number)
2145
2146 =item countrycode
2147
2148 Country code (to be provisioned as a service)
2149
2150 =item phonenum
2151
2152 Phone number (to be provisioned as a service)
2153
2154 =item pin
2155
2156 Voicemail PIN
2157
2158 =back
2159
2160 Returns a hash reference with the following keys:
2161
2162 =over 4
2163
2164 =item error
2165
2166 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)
2167
2168 =back
2169
2170 =item regionselector HASHREF | LIST
2171
2172 Takes as input a hashref or list of key/value pairs with the following keys:
2173
2174 =over 4
2175
2176 =item selected_county
2177
2178 Currently selected county
2179
2180 =item selected_state
2181
2182 Currently selected state
2183
2184 =item selected_country
2185
2186 Currently selected country
2187
2188 =item prefix
2189
2190 Specify a unique prefix string  if you intend to use the HTML output multiple time son one page.
2191
2192 =item onchange
2193
2194 Specify a javascript subroutine to call on changes
2195
2196 =item default_state
2197
2198 Default state
2199
2200 =item default_country
2201
2202 Default country
2203
2204 =item locales
2205
2206 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>.
2207
2208 =back
2209
2210 Returns a list consisting of three HTML fragments for county selection,
2211 state selection and country selection, respectively.
2212
2213 =cut
2214
2215 #false laziness w/FS::cust_main_county (this is currently the "newest" version)
2216 sub regionselector {
2217   my $param;
2218   if ( ref($_[0]) ) {
2219     $param = shift;
2220   } else {
2221     $param = { @_ };
2222   }
2223   $param->{'selected_country'} ||= $param->{'default_country'};
2224   $param->{'selected_state'} ||= $param->{'default_state'};
2225
2226   my $prefix = exists($param->{'prefix'}) ? $param->{'prefix'} : '';
2227
2228   my $countyflag = 0;
2229
2230   my %cust_main_county;
2231
2232 #  unless ( @cust_main_county ) { #cache
2233     #@cust_main_county = qsearch('cust_main_county', {} );
2234     #foreach my $c ( @cust_main_county ) {
2235     foreach my $c ( @{ $param->{'locales'} } ) {
2236       #$countyflag=1 if $c->county;
2237       $countyflag=1 if $c->{county};
2238       #push @{$cust_main_county{$c->country}{$c->state}}, $c->county;
2239       #$cust_main_county{$c->country}{$c->state}{$c->county} = 1;
2240       $cust_main_county{$c->{country}}{$c->{state}}{$c->{county}} = 1;
2241     }
2242 #  }
2243   $countyflag=1 if $param->{selected_county};
2244
2245   my $script_html = <<END;
2246     <SCRIPT>
2247     function opt(what,value,text) {
2248       var optionName = new Option(text, value, false, false);
2249       var length = what.length;
2250       what.options[length] = optionName;
2251     }
2252     function ${prefix}country_changed(what) {
2253       country = what.options[what.selectedIndex].text;
2254       for ( var i = what.form.${prefix}state.length; i >= 0; i-- )
2255           what.form.${prefix}state.options[i] = null;
2256 END
2257       #what.form.${prefix}state.options[0] = new Option('', '', false, true);
2258
2259   foreach my $country ( sort keys %cust_main_county ) {
2260     $script_html .= "\nif ( country == \"$country\" ) {\n";
2261     foreach my $state ( sort keys %{$cust_main_county{$country}} ) {
2262       my $text = $state || '(n/a)';
2263       $script_html .= qq!opt(what.form.${prefix}state, "$state", "$text");\n!;
2264     }
2265     $script_html .= "}\n";
2266   }
2267
2268   $script_html .= <<END;
2269     }
2270     function ${prefix}state_changed(what) {
2271 END
2272
2273   if ( $countyflag ) {
2274     $script_html .= <<END;
2275       state = what.options[what.selectedIndex].text;
2276       country = what.form.${prefix}country.options[what.form.${prefix}country.selectedIndex].text;
2277       for ( var i = what.form.${prefix}county.length; i >= 0; i-- )
2278           what.form.${prefix}county.options[i] = null;
2279 END
2280
2281     foreach my $country ( sort keys %cust_main_county ) {
2282       $script_html .= "\nif ( country == \"$country\" ) {\n";
2283       foreach my $state ( sort keys %{$cust_main_county{$country}} ) {
2284         $script_html .= "\nif ( state == \"$state\" ) {\n";
2285           #foreach my $county ( sort @{$cust_main_county{$country}{$state}} ) {
2286           foreach my $county ( sort keys %{$cust_main_county{$country}{$state}} ) {
2287             my $text = $county || '(n/a)';
2288             $script_html .=
2289               qq!opt(what.form.${prefix}county, "$county", "$text");\n!;
2290           }
2291         $script_html .= "}\n";
2292       }
2293       $script_html .= "}\n";
2294     }
2295   }
2296
2297   $script_html .= <<END;
2298     }
2299     </SCRIPT>
2300 END
2301
2302   my $county_html = $script_html;
2303   if ( $countyflag ) {
2304     $county_html .= qq!<SELECT NAME="${prefix}county" onChange="$param->{'onchange'}">!;
2305     foreach my $county (
2306       sort keys %{ $cust_main_county{$param->{'selected_country'}}{$param->{'selected_state'}} }
2307     ) {
2308       my $text = $county || '(n/a)';
2309       $county_html .= qq!<OPTION VALUE="$county"!.
2310                       ($county eq $param->{'selected_county'} ?
2311                         ' SELECTED>' :
2312                         '>'
2313                       ).
2314                       $text.
2315                       '</OPTION>';
2316     }
2317     $county_html .= '</SELECT>';
2318   } else {
2319     $county_html .=
2320       qq!<INPUT TYPE="hidden" NAME="${prefix}county" VALUE="$param->{'selected_county'}">!;
2321   }
2322
2323   my $state_html = qq!<SELECT NAME="${prefix}state" !.
2324                    qq!onChange="${prefix}state_changed(this); $param->{'onchange'}">!;
2325   foreach my $state ( sort keys %{ $cust_main_county{$param->{'selected_country'}} } ) {
2326     my $text = $state || '(n/a)';
2327     my $selected = $state eq $param->{'selected_state'} ? 'SELECTED' : '';
2328     $state_html .= "\n<OPTION $selected VALUE=\"$state\">$text</OPTION>"
2329   }
2330   $state_html .= '</SELECT>';
2331
2332   my $country_html = '';
2333   if ( scalar( keys %cust_main_county ) > 1 )  {
2334
2335     $country_html = qq(<SELECT NAME="${prefix}country" ).
2336                     qq(onChange="${prefix}country_changed(this); ).
2337                                  $param->{'onchange'}.
2338                                '"'.
2339                       '>';
2340     my $countrydefault = $param->{default_country} || 'US';
2341     foreach my $country (
2342       sort { ($b eq $countrydefault) <=> ($a eq $countrydefault) or $a cmp $b }
2343         keys %cust_main_county
2344     ) {
2345       my $selected = $country eq $param->{'selected_country'}
2346                        ? ' SELECTED'
2347                        : '';
2348       $country_html .= "\n<OPTION $selected>$country</OPTION>"
2349     }
2350     $country_html .= '</SELECT>';
2351   } else {
2352
2353     $country_html = qq(<INPUT TYPE="hidden" NAME="${prefix}country" ).
2354                             ' VALUE="'. (keys %cust_main_county )[0]. '">';
2355
2356   }
2357
2358   ($county_html, $state_html, $country_html);
2359
2360 }
2361
2362 sub regionselector_hashref {
2363   my ($county_html, $state_html, $country_html) = regionselector(@_);
2364   {
2365     'county_html'  => $county_html,
2366     'state_html'   => $state_html,
2367     'country_html' => $country_html,
2368   };
2369 }
2370
2371 =item location_form HASHREF | LIST
2372
2373 Takes as input a hashref or list of key/value pairs with the following keys:
2374
2375 =over 4
2376
2377 =item session_id
2378
2379 Current customer session_id
2380
2381 =item no_asterisks
2382
2383 Omit red asterisks from required fields.
2384
2385 =item address1_label
2386
2387 Label for first address line.
2388
2389 =back
2390
2391 Returns an HTML fragment for a location form (address, city, state, zip,
2392 country)
2393
2394 =cut
2395
2396 sub location_form {
2397   my $param;
2398   if ( ref($_[0]) ) {
2399     $param = shift;
2400   } else {
2401     $param = { @_ };
2402   }
2403
2404   my $session_id = delete $param->{'session_id'};
2405
2406   my $rv = mason_comp( 'session_id' => $session_id,
2407                        'comp'       => '/elements/location.html',
2408                        'args'       => [ %$param ],
2409                      );
2410
2411   #hmm.
2412   $rv->{'error'} || $rv->{'output'};
2413
2414 }
2415
2416
2417 #=item expselect HASHREF | LIST
2418 #
2419 #Takes as input a hashref or list of key/value pairs with the following keys:
2420 #
2421 #=over 4
2422 #
2423 #=item prefix - Specify a unique prefix string  if you intend to use the HTML output multiple time son one page.
2424 #
2425 #=item date - current date, in yyyy-mm-dd or m-d-yyyy format
2426 #
2427 #=back
2428
2429 =item expselect PREFIX [ DATE ]
2430
2431 Takes as input a unique prefix string and the current expiration date, in
2432 yyyy-mm-dd or m-d-yyyy format
2433
2434 Returns an HTML fragments for expiration date selection.
2435
2436 =cut
2437
2438 sub expselect {
2439   #my $param;
2440   #if ( ref($_[0]) ) {
2441   #  $param = shift;
2442   #} else {
2443   #  $param = { @_ };
2444   #my $prefix = $param->{'prefix'};
2445   #my $prefix = exists($param->{'prefix'}) ? $param->{'prefix'} : '';
2446   #my $date =   exists($param->{'date'})   ? $param->{'date'}   : '';
2447   my $prefix = shift;
2448   my $date = scalar(@_) ? shift : '';
2449
2450   my( $m, $y ) = ( 0, 0 );
2451   if ( $date  =~ /^(\d{4})-(\d{2})-\d{2}$/ ) { #PostgreSQL date format
2452     ( $m, $y ) = ( $2, $1 );
2453   } elsif ( $date =~ /^(\d{1,2})-(\d{1,2}-)?(\d{4}$)/ ) {
2454     ( $m, $y ) = ( $1, $3 );
2455   }
2456   my $return = qq!<SELECT NAME="$prefix!. qq!_month" SIZE="1">!;
2457   for ( 1 .. 12 ) {
2458     $return .= qq!<OPTION VALUE="$_"!;
2459     $return .= " SELECTED" if $_ == $m;
2460     $return .= ">$_";
2461   }
2462   $return .= qq!</SELECT>/<SELECT NAME="$prefix!. qq!_year" SIZE="1">!;
2463   my @t = localtime;
2464   my $thisYear = $t[5] + 1900;
2465   for ( ($thisYear > $y && $y > 0 ? $y : $thisYear) .. ($thisYear+10) ) {
2466     $return .= qq!<OPTION VALUE="$_"!;
2467     $return .= " SELECTED" if $_ == $y;
2468     $return .= ">$_";
2469   }
2470   $return .= "</SELECT>";
2471
2472   $return;
2473 }
2474
2475 =item popselector HASHREF | LIST
2476
2477 Takes as input a hashref or list of key/value pairs with the following keys:
2478
2479 =over 4
2480
2481 =item popnum
2482
2483 Access number number
2484
2485 =item pops
2486
2487 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>.
2488
2489 =back
2490
2491 Returns an HTML fragment for access number selection.
2492
2493 =cut
2494
2495 #horrible false laziness with FS/FS/svc_acct_pop.pm::popselector
2496 sub popselector {
2497   my $param;
2498   if ( ref($_[0]) ) {
2499     $param = shift;
2500   } else {
2501     $param = { @_ };
2502   }
2503   my $popnum = $param->{'popnum'};
2504   my $pops = $param->{'pops'};
2505
2506   return '<INPUT TYPE="hidden" NAME="popnum" VALUE="">' unless @$pops;
2507   return $pops->[0]{city}. ', '. $pops->[0]{state}.
2508          ' ('. $pops->[0]{ac}. ')/'. $pops->[0]{exch}. '-'. $pops->[0]{loc}.
2509          '<INPUT TYPE="hidden" NAME="popnum" VALUE="'. $pops->[0]{popnum}. '">'
2510     if scalar(@$pops) == 1;
2511
2512   my %pop = ();
2513   my %popnum2pop = ();
2514   foreach (@$pops) {
2515     push @{ $pop{ $_->{state} }->{ $_->{ac} } }, $_;
2516     $popnum2pop{$_->{popnum}} = $_;
2517   }
2518
2519   my $text = <<END;
2520     <SCRIPT>
2521     function opt(what,href,text) {
2522       var optionName = new Option(text, href, false, false)
2523       var length = what.length;
2524       what.options[length] = optionName;
2525     }
2526 END
2527
2528   my $init_popstate = $param->{'init_popstate'};
2529   if ( $init_popstate ) {
2530     $text .= '<INPUT TYPE="hidden" NAME="init_popstate" VALUE="'.
2531              $init_popstate. '">';
2532   } else {
2533     $text .= <<END;
2534       function acstate_changed(what) {
2535         state = what.options[what.selectedIndex].text;
2536         what.form.popac.options.length = 0
2537         what.form.popac.options[0] = new Option("Area code", "-1", false, true);
2538 END
2539   }
2540
2541   my @states = $init_popstate ? ( $init_popstate ) : keys %pop;
2542   foreach my $state ( sort { $a cmp $b } @states ) {
2543     $text .= "\nif ( state == \"$state\" ) {\n" unless $init_popstate;
2544
2545     foreach my $ac ( sort { $a cmp $b } keys %{ $pop{$state} }) {
2546       $text .= "opt(what.form.popac, \"$ac\", \"$ac\");\n";
2547       if ($ac eq $param->{'popac'}) {
2548         $text .= "what.form.popac.options[what.form.popac.length-1].selected = true;\n";
2549       }
2550     }
2551     $text .= "}\n" unless $init_popstate;
2552   }
2553   $text .= "popac_changed(what.form.popac)}\n";
2554
2555   $text .= <<END;
2556   function popac_changed(what) {
2557     ac = what.options[what.selectedIndex].text;
2558     what.form.popnum.options.length = 0;
2559     what.form.popnum.options[0] = new Option("City", "-1", false, true);
2560
2561 END
2562
2563   foreach my $state ( @states ) {
2564     foreach my $popac ( keys %{ $pop{$state} } ) {
2565       $text .= "\nif ( ac == \"$popac\" ) {\n";
2566
2567       foreach my $pop ( @{$pop{$state}->{$popac}}) {
2568         my $o_popnum = $pop->{popnum};
2569         my $poptext =  $pop->{city}. ', '. $pop->{state}.
2570                        ' ('. $pop->{ac}. ')/'. $pop->{exch}. '-'. $pop->{loc};
2571
2572         $text .= "opt(what.form.popnum, \"$o_popnum\", \"$poptext\");\n";
2573         if ($popnum == $o_popnum) {
2574           $text .= "what.form.popnum.options[what.form.popnum.length-1].selected = true;\n";
2575         }
2576       }
2577       $text .= "}\n";
2578     }
2579   }
2580
2581
2582   $text .= "}\n</SCRIPT>\n";
2583
2584   $param->{'acstate'} = '' unless defined($param->{'acstate'});
2585
2586   $text .=
2587     qq!<TABLE CELLPADDING="0"><TR><TD><SELECT NAME="acstate"! .
2588     qq!SIZE=1 onChange="acstate_changed(this)"><OPTION VALUE=-1>State!;
2589   $text .= "<OPTION" . ($_ eq $param->{'acstate'} ? " SELECTED" : "") .
2590            ">$_" foreach sort { $a cmp $b } @states;
2591   $text .= '</SELECT>'; #callback? return 3 html pieces?  #'</TD>';
2592
2593   $text .=
2594     qq!<SELECT NAME="popac" SIZE=1 onChange="popac_changed(this)">!.
2595     qq!<OPTION>Area code</SELECT></TR><TR VALIGN="top">!;
2596
2597   $text .= qq!<TR><TD><SELECT NAME="popnum" SIZE=1 STYLE="width: 20em"><OPTION>City!;
2598
2599
2600   #comment this block to disable initial list polulation
2601   my @initial_select = ();
2602   if ( scalar( @$pops ) > 100 ) {
2603     push @initial_select, $popnum2pop{$popnum} if $popnum2pop{$popnum};
2604   } else {
2605     @initial_select = @$pops;
2606   }
2607   foreach my $pop ( sort { $a->{state} cmp $b->{state} } @initial_select ) {
2608     $text .= qq!<OPTION VALUE="!. $pop->{popnum}. '"'.
2609              ( ( $popnum && $pop->{popnum} == $popnum ) ? ' SELECTED' : '' ). ">".
2610              $pop->{city}. ', '. $pop->{state}.
2611                ' ('. $pop->{ac}. ')/'. $pop->{exch}. '-'. $pop->{loc};
2612   }
2613
2614   $text .= qq!</SELECT></TD></TR></TABLE>!;
2615
2616   $text;
2617
2618 }
2619
2620 =item domainselector HASHREF | LIST
2621
2622 Takes as input a hashref or list of key/value pairs with the following keys:
2623
2624 =over 4
2625
2626 =item pkgnum
2627
2628 Package number
2629
2630 =item domsvc
2631
2632 Service number of the selected item.
2633
2634 =back
2635
2636 Returns an HTML fragment for domain selection.
2637
2638 =cut
2639
2640 sub domainselector {
2641   my $param;
2642   if ( ref($_[0]) ) {
2643     $param = shift;
2644   } else {
2645     $param = { @_ };
2646   }
2647   my $domsvc= $param->{'domsvc'};
2648   my $rv =
2649       domain_select_hash(map {$_ => $param->{$_}} qw(pkgnum svcpart pkgpart) );
2650   my $domains = $rv->{'domains'};
2651   $domsvc = $rv->{'domsvc'} unless $domsvc;
2652
2653   return '<INPUT TYPE="hidden" NAME="domsvc" VALUE="">'
2654     unless scalar(keys %$domains);
2655
2656   if (scalar(keys %$domains) == 1) {
2657     my $key;
2658     foreach(keys %$domains) {
2659       $key = $_;
2660     }
2661     return '<TR><TD ALIGN="right">Domain</TD><TD>'. $domains->{$key}.
2662            '<INPUT TYPE="hidden" NAME="domsvc" VALUE="'. $key. '"></TD></TR>'
2663   }
2664
2665   my $text .= qq!<TR><TD ALIGN="right">Domain</TD><TD><SELECT NAME="domsvc" SIZE=1 STYLE="width: 20em">!;
2666
2667   $text .= '<OPTION>(Choose Domain)' unless $domsvc;
2668
2669   foreach my $domain ( sort { $domains->{$a} cmp $domains->{$b} } keys %$domains ) {
2670     $text .= qq!<OPTION VALUE="!. $domain. '"'.
2671              ( ( $domsvc && $domain == $domsvc ) ? ' SELECTED' : '' ). ">".
2672              $domains->{$domain};
2673   }
2674
2675   $text .= qq!</SELECT></TD></TR>!;
2676
2677   $text;
2678
2679 }
2680
2681 =item didselector HASHREF | LIST
2682
2683 Takes as input a hashref or list of key/value pairs with the following keys:
2684
2685 =over 4
2686
2687 =item field
2688
2689 Field name for the returned HTML fragment.
2690
2691 =item svcpart
2692
2693 Service definition (see L<FS::part_svc>)
2694
2695 =back
2696
2697 Returns an HTML fragment for DID selection.
2698
2699 =cut
2700
2701 sub didselector {
2702   my $param;
2703   if ( ref($_[0]) ) {
2704     $param = shift;
2705   } else {
2706     $param = { @_ };
2707   }
2708
2709   my $rv = mason_comp( 'comp'=>'/elements/select-did.html',
2710                        'args'=>[ %$param ],
2711                      );
2712
2713   #hmm.
2714   $rv->{'error'} || $rv->{'output'};
2715
2716 }
2717
2718 =back
2719
2720 =head1 RESELLER FUNCTIONS
2721
2722 Note: Resellers can also use the B<signup_info> and B<new_customer> functions
2723 with their active session, and the B<customer_info> and B<order_pkg> functions
2724 with their active session and an additional I<custnum> parameter.
2725
2726 For the most part, development of the reseller web interface has been
2727 superceded by agent-virtualized access to the backend.
2728
2729 =over 4
2730
2731 =item agent_login
2732
2733 Agent login
2734
2735 =item agent_info
2736
2737 Agent info
2738
2739 =item agent_list_customers
2740
2741 List agent's customers.
2742
2743 =back
2744
2745 =head1 BUGS
2746
2747 =head1 SEE ALSO
2748
2749 L<freeside-selfservice-clientd>, L<freeside-selfservice-server>
2750
2751 =cut
2752
2753 1;
2754