fs_selfservice/FS-SelfService/SelfService.pm

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