fs_selfservice/FS-SelfService/SelfService.pm

   1 package FS::SelfService;
   2
   3 use strict;
   4 use vars qw($VERSION @ISA @EXPORT_OK $socket %autoload $tag);
   5 use Exporter;
   6 use Socket;
   7 use FileHandle;
   8 #use IO::Handle;
   9 use IO::Select;
  10 use Storable qw(nstore_fd fd_retrieve);
  11
  12 $VERSION = '0.03';
  13
  14 @ISA = qw( Exporter );
  15
  16 $socket =  "/usr/local/freeside/selfservice_socket";
  17 $socket .= '.'.$tag if defined $tag && length($tag);
  18
  19 #maybe should ask ClientAPI for this list
  20 %autoload = (
  21   'passwd'          => 'passwd/passwd',
  22   'chfn'            => 'passwd/passwd',
  23   'chsh'            => 'passwd/passwd',
  24   'login'           => 'MyAccount/login',
  25   'customer_info'   => 'MyAccount/customer_info',
  26   'invoice'         => 'MyAccount/invoice',
  27   'cancel'          => 'MyAccount/cancel',
  28   'payment_info'    => 'MyAccount/payment_info',
  29   'process_payment' => 'MyAccount/process_payment',
  30   'list_pkgs'       => 'MyAccount/list_pkgs',
  31   'order_pkg'       => 'MyAccount/order_pkg',
  32   'cancel_pkg'      => 'MyAccount/cancel_pkg',
  33   'signup_info'     => 'Signup/signup_info',
  34   'new_customer'    => 'Signup/new_customer',
  35 );
  36 @EXPORT_OK = keys %autoload;
  37
  38 $ENV{'PATH'} ='/usr/bin:/usr/ucb:/bin';
  39 $ENV{'SHELL'} = '/bin/sh';
  40 $ENV{'IFS'} = " \t\n";
  41 $ENV{'CDPATH'} = '';
  42 $ENV{'ENV'} = '';
  43 $ENV{'BASH_ENV'} = '';
  44
  45 my $freeside_uid = scalar(getpwnam('freeside'));
  46 die "not running as the freeside user\n" if $> != $freeside_uid;
  47
  48 foreach my $autoload ( keys %autoload ) {
  49
  50   my $eval =
  51   "sub $autoload { ". '
  52                    my $param;
  53                    if ( ref($_[0]) ) {
  54                      $param = shift;
  55                    } else {
  56                      $param = { @_ };
  57                    }
  58
  59                    $param->{_packet} = \''. $autoload{$autoload}. '\';
  60
  61                    simple_packet($param);
  62                  }';
  63
  64   eval $eval;
  65   die $@ if $@;
  66
  67 }
  68
  69 sub simple_packet {
  70   my $packet = shift;
  71   socket(SOCK, PF_UNIX, SOCK_STREAM, 0) or die "socket: $!";
  72   connect(SOCK, sockaddr_un($socket)) or die "connect: $!";
  73   nstore_fd($packet, \*SOCK) or die "can't send packet: $!";
  74   SOCK->flush;
  75
  76   #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
  77
  78   #block until there is a message on socket
  79 #  my $w = new IO::Select;
  80 #  $w->add(\*SOCK);
  81 #  my @wait = $w->can_read;
  82   my $return = fd_retrieve(\*SOCK) or die "error reading result: $!";
  83   die $return->{'_error'} if defined $return->{_error} && $return->{_error};
  84
  85   $return;
  86 }
  87
  88 =head1 NAME
  89
  90 FS::SelfService - Freeside self-service API
  91
  92 =head1 SYNOPSIS
  93
  94   # password and shell account changes
  95   use FS::SelfService qw(passwd chfn chsh);
  96
  97   # "my account" functionality
  98   use FS::SelfService qw( login customer_info invoice cancel payment_info process_payment );
  99
 100   my $rv = login( { 'username' => $username,
 101                     'domain'   => $domain,
 102                     'password' => $password,
 103                   }
 104                 );
 105
 106   if ( $rv->{'error'} ) {
 107     #handle login error...
 108   } else {
 109     #successful login
 110     my $session_id = $rv->{'session_id'};
 111   }
 112
 113   my $customer_info = customer_info( { 'session_id' => $session_id } );
 114
 115   #payment_info and process_payment are available in 1.5+ only
 116   my $payment_info = payment_info) { 'session_id' => $session_id } );
 117
 118   #!!! process_payment example
 119
 120   #!!! list_pkgs example
 121
 122   #!!! order_pkg example
 123
 124   #!!! cancel_pkg example
 125
 126   # signup functionality
 127   use FS::SelfService qw( signup_info new_customer );
 128
 129   my $signup_info = signup_info;
 130
 131   $rv = new_customer( {
 132                         'first'            => $first,
 133                         'last'             => $last,
 134                         'company'          => $company,
 135                         'address1'         => $address1,
 136                         'address2'         => $address2,
 137                         'city'             => $city,
 138                         'state'            => $state,
 139                         'zip'              => $zip,
 140                         'country'          => $country,
 141                         'daytime'          => $daytime,
 142                         'night'            => $night,
 143                         'fax'              => $fax,
 144                         'payby'            => $payby,
 145                         'payinfo'          => $payinfo,
 146                         'paycvv'           => $paycvv,
 147                         'paydate'          => $paydate,
 148                         'payname'          => $payname,
 149                         'invoicing_list'   => $invoicing_list,
 150                         'referral_custnum' => $referral_custnum,
 151                         'pkgpart'          => $pkgpart,
 152                         'username'         => $username,
 153                         '_password'        => $password,
 154                         'popnum'           => $popnum,
 155                         'agentnum'         => $agentnum,
 156                       }
 157                     );
 158
 159   my $error = $rv->{'error'};
 160   if ( $error eq '_decline' ) {
 161     print_decline();
 162   } elsif ( $error ) {
 163     reprint_signup();
 164   } else {
 165     print_success();
 166   }
 167
 168 =head1 DESCRIPTION
 169
 170 Use this API to implement your own client "self-service" module.
 171
 172 If you just want to customize the look of the existing "self-service" module,
 173 see XXXX instead.
 174
 175 =head1 PASSWORD, GECOS, SHELL CHANGING FUNCTIONS
 176
 177 =over 4
 178
 179 =item passwd
 180
 181 =item chfn
 182
 183 =item chsh
 184
 185 =back
 186
 187 =head1 "MY ACCOUNT" FUNCTIONS
 188
 189 =over 4
 190
 191 =item login HASHREF
 192
 193 Creates a user session.  Takes a hash reference as parameter with the
 194 following keys:
 195
 196 =over 4
 197
 198 =item username
 199
 200 =item domain
 201
 202 =item password
 203
 204 =back
 205
 206 Returns a hash reference with the following keys:
 207
 208 =over 4
 209
 210 =item error
 211
 212 Empty on success, or an error message on errors.
 213
 214 =item session_id
 215
 216 Session identifier for successful logins
 217
 218 =back
 219
 220 =item customer_info HASHREF
 221
 222 Returns general customer information.
 223
 224 Takes a hash reference as parameter with a single key: B<session_id>
 225
 226 Returns a hash reference with the following keys:
 227
 228 =over 4
 229
 230 =item name
 231
 232 Customer name
 233
 234 =item balance
 235
 236 Balance owed
 237
 238 =item open
 239
 240 Array reference of hash references of open inoices.  Each hash reference has
 241 the following keys: invnum, date, owed
 242
 243 =item small_custview
 244
 245 An HTML fragment containing shipping and billing addresses.
 246
 247 =back
 248
 249 =item invoice HASHREF
 250
 251 Returns an invoice.  Takes a hash reference as parameter with two keys:
 252 session_id and invnum
 253
 254 Returns a hash reference with the following keys:
 255
 256 =over 4
 257
 258 =item error
 259
 260 Empty on success, or an error message on errors
 261
 262 =item invnum
 263
 264 Invoice number
 265
 266 =item invoice_text
 267
 268 Invoice text
 269
 270 =back
 271
 272 =item cancel HASHREF
 273
 274 Cancels this customer.
 275
 276 Takes a hash reference as parameter with a single key: B<session_id>
 277
 278 Returns a hash reference with a single key, B<error>, which is empty on
 279 success or an error message on errors.
 280
 281 =item payment_info HASHREF
 282
 283 Returns information that may be useful in displaying a payment page.
 284
 285 Takes a hash reference as parameter with a single key: B<session_id>.
 286
 287 Returns a hash reference with the following keys:
 288
 289 =over 4
 290
 291 =item error
 292
 293 Empty on success, or an error message on errors
 294
 295 =item balance
 296
 297 Balance owed
 298
 299 =item payname
 300
 301 Exact name on credit card (CARD/DCRD)
 302
 303 =item address1
 304
 305 =item address2
 306
 307 =item city
 308
 309 =item state
 310
 311 =item zip
 312
 313 =item payby
 314
 315 Customer's current default payment type.
 316
 317 =item card_type
 318
 319 For CARD/DCRD payment types, the card type (Visa card, MasterCard, Discover card, American Express card, etc.)
 320
 321 =item payinfo
 322
 323 For CARD/DCRD payment types, the card number
 324
 325 =item month
 326
 327 For CARD/DCRD payment types, expiration month
 328
 329 =item year
 330
 331 For CARD/DCRD payment types, expiration year
 332
 333 =item cust_main_county
 334
 335 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.
 336
 337 =item states
 338
 339 Array reference of all states in the current default country.
 340
 341 =item card_types
 342
 343 Hash reference of card types; keys are card types, values are the exact strings
 344 passed to the process_payment function
 345
 346 =item paybatch
 347
 348 Unique transaction identifier (prevents multiple charges), passed to the
 349 process_payment function
 350
 351 =back
 352
 353 =item process_payment HASHREF
 354
 355 Processes a payment and possible change of address or payment type.  Takes a
 356 hash reference as parameter with the following keys:
 357
 358 =over 4
 359
 360 =item session_id
 361
 362 =item save
 363
 364 If true, address and card information entered will be saved for subsequent
 365 transactions.
 366
 367 =item auto
 368
 369 If true, future credit card payments will be done automatically (sets payby to
 370 CARD).  If false, future credit card payments will be done on-demand (sets
 371 payby to DCRD).  This option only has meaning if B<save> is set true.
 372
 373 =item payname
 374
 375 =item address1
 376
 377 =item address2
 378
 379 =item city
 380
 381 =item state
 382
 383 =item zip
 384
 385 =item payinfo
 386
 387 Card number
 388
 389 =item month
 390
 391 Card expiration month
 392
 393 =item year
 394
 395 Card expiration year
 396
 397 =item paybatch
 398
 399 Unique transaction identifier, returned from the payment_info function.
 400 Prevents multiple charges.
 401
 402 =back
 403
 404 Returns a hash reference with a single key, B<error>, empty on success, or an
 405 error message on errors
 406
 407 =item list_pkgs
 408
 409 Returns package information for this customer.
 410
 411 Takes a hash reference as parameter with a single key: B<session_id>
 412
 413 Returns a hash reference containing customer package information.  The hash reference contains the following keys:
 414
 415 =over 4
 416
 417 =item cust_pkg HASHREF
 418
 419 Array reference of hash references, each of which has the fields of a cust_pkg record (see L<FS::cust_pkg>).  Note these are not FS::cust_pkg objects, but hash references of columns and values.
 420
 421 =back
 422
 423 =item order_pkg
 424
 425 Orders a package for this customer.
 426
 427 Takes a hash reference as parameter with the following keys:
 428
 429 =over 4
 430
 431 =item session_id
 432
 433 =item pkgpart
 434
 435 =item svcpart
 436
 437 optional svcpart, required only if the package definition does not contain
 438 one svc_acct service definition with quantity 1 (it may contain others with
 439 quantity >1)
 440
 441 =item username
 442
 443 =item _password
 444
 445 =item sec_phrase
 446
 447 =item popnum
 448
 449 =back
 450
 451 Returns a hash reference with a single key, B<error>, empty on success, or an
 452 error message on errors.  The special error '_decline' is returned for
 453 declined transactions.
 454
 455 =item cancel_pkg
 456
 457 Cancels a package for this customer.
 458
 459 Takes a hash reference as parameter with the following keys:
 460
 461 =over 4
 462
 463 =item session_id
 464
 465 =item pkgpart
 466
 467 =back
 468
 469 Returns a hash reference with a single key, B<error>, empty on success, or an
 470 error message on errors.
 471
 472 =back
 473
 474 =head1 SIGNUP FUNCTIONS
 475
 476 =over 4
 477
 478 =item signup_info
 479
 480 Returns a hash reference containing information that may be useful in
 481 displaying a signup page.  The hash reference contains the following keys:
 482
 483 =over 4
 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 part_pkg
 490
 491 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.
 492
 493 =item agent
 494
 495 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.
 496
 497 =item agentnum2part_pkg
 498
 499 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.
 500
 501 =item svc_acct_pop
 502
 503 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.
 504
 505 =item security_phrase
 506
 507 True if the "security_phrase" feature is enabled
 508
 509 =item payby
 510
 511 Array reference of acceptable payment types for signup
 512
 513 =over 4
 514
 515 =item CARD (credit card - automatic)
 516
 517 =item DCRD (credit card - on-demand - version 1.5+ only)
 518
 519 =item CHEK (electronic check - automatic)
 520
 521 =item DCHK (electronic check - on-demand - version 1.5+ only)
 522
 523 =item LECB (Phone bill billing)
 524
 525 =item BILL (billing, not recommended for signups)
 526
 527 =item COMP (free, definately not recommended for signups)
 528
 529 =item PREPAY (special billing type: applies a credit (see FS::prepay_credit) and sets billing type to BILL)
 530
 531 =back
 532
 533 =item cvv_enabled
 534
 535 True if CVV features are available (1.5+ or 1.4.2 with CVV schema patch)
 536
 537 =item msgcat
 538
 539 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".
 540
 541 =item statedefault
 542
 543 Default state
 544
 545 =item countrydefault
 546
 547 Default country
 548
 549 =back
 550
 551 =item new_customer HASHREF
 552
 553 Creates a new customer.  Takes a hash reference as parameter with the
 554 following keys:
 555
 556 =over 4
 557
 558 =item first - first name (required)
 559
 560 =item last - last name (required)
 561
 562 =item ss (not typically collected; mostly used for ACH transactions)
 563
 564 =item company
 565
 566 =item address1 (required)
 567
 568 =item address2
 569
 570 =item city (required)
 571
 572 =item county
 573
 574 =item state (required)
 575
 576 =item zip (required)
 577
 578 =item daytime - phone
 579
 580 =item night - phone
 581
 582 =item fax - phone
 583
 584 =item payby - CARD, DCRD, CHEK, DCHK, LECB, BILL, COMP or PREPAY (see L</signup_info> (required)
 585
 586 =item payinfo - Card number for CARD/DCRD, account_number@aba_number for CHEK/DCHK, prepaid "pin" for PREPAY, purchase order number for BILL
 587
 588 =item paycvv - Credit card CVV2 number (1.5+ or 1.4.2 with CVV schema patch)
 589
 590 =item paydate - Expiration date for CARD/DCRD
 591
 592 =item payname - Exact name on credit card for CARD/DCRD, bank name for CHEK/DCHK
 593
 594 =item invoicing_list - 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),
 595
 596 =item referral_custnum - referring customer number
 597
 598 =item pkgpart - pkgpart of initial package
 599
 600 =item username
 601
 602 =item _password
 603
 604 =item sec_phrase - security phrase
 605
 606 =item popnum - access number (index, not the literal number)
 607
 608 =item agentnum - agent number
 609
 610 =back
 611
 612 Returns a hash reference with the following keys:
 613
 614 =over 4
 615
 616 =item error 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 Sysadmin | View/Edit message catalog)
 617
 618 =back
 619
 620
 621 =back
 622
 623 =head1 BUGS
 624
 625 =head1 SEE ALSO
 626
 627 L<freeside-selfservice-clientd>, L<freeside-selfservice-server>
 628
 629 =cut
 630
 631 1;
 632