From dad321f0c9bdd0bca4eddecdd618c8f79d768c6f Mon Sep 17 00:00:00 2001
From: ivan <ivan>
Date: Tue, 24 Nov 2009 02:28:57 +0000
Subject: [PATCH] Add beginning of introspection interface for processor
 modules.

---
 Changes                     |  1 +
 OnlinePayment.pm            | 74 +++++++++++++++++++++++++++++++++++++++++----
 notes_for_module_writers_v3 | 58 ++++++++++++++++++++++++++++++++++-
 3 files changed, 126 insertions(+), 7 deletions(-)

diff --git a/Changes b/Changes
index be1a41f..40f2d26 100644
--- a/Changes
+++ b/Changes
@@ -5,6 +5,7 @@ Revision history for Perl extension Business::OnlinePayment.
           po_number.
         - Add return fields to documentation: order_number, avs_code,
           cvv2_response, response_code, response_headers, response_page.
+        - Add beginning of introspection interface for processor modules.
 
 3.00     Mon Aug 17 15:55:11 PDT 2009
         - It finally happened.
diff --git a/OnlinePayment.pm b/OnlinePayment.pm
index a249981..7cdc10e 100644
--- a/OnlinePayment.pm
+++ b/OnlinePayment.pm
@@ -1,7 +1,7 @@
 package Business::OnlinePayment;
 
 use strict;
-use vars qw($VERSION);
+use vars qw($VERSION %_info_handler);
 use Carp;
 
 require 5.005;
@@ -35,6 +35,47 @@ my @methods = qw(
     response_page
 );
 
+#fallback
+sub _info {
+  my $class = shift;
+  ( my $gw = $class ) =~ s/^Business::OnlinePayment:://;
+  {
+    'info_compat'    => '0.00',
+    'gateway_name'   => $gw,
+    'module_notes'   => "Module does not yet provide info.",
+  };
+}
+
+#allow classes to declare info in a flexible way, but return normalized info
+%_info_handler = (
+  'supported_types'   => sub {
+    my( $class, $v ) = @_;
+    my $types = ref($v) ? $v : [ $v ];
+    $types = { map { $_=>1 } @$types } if ref($v) eq 'ARRAY';
+    $types;
+  },
+  'supported_actions' => sub {
+    my( $class, $v ) = @_;
+    return $v if ref($v) eq 'HASH';
+    $v = [ $v ] unless ref($v);
+    my $types = $class->info('supported_types');
+    { map { $_ => $v } keys %$types };
+  },
+);
+
+sub info {
+  my $class = shift;
+  my $info = $class->_info;
+  if ( @_ ) {
+    my $key = shift;
+    exists($_info_handler{$key})
+      ? &{ $_info_handler{$key} }( $class, $info->{$key} )
+      : $info->{$key};
+  } else {
+    wantarray ? ( keys %$info ) : [ keys %$info ];
+  }
+}
+
 sub new {
     my($class,$processor,%data) = @_;
 
@@ -294,10 +335,27 @@ processors support all transaction types.
 
 =item action
 
-What to do with the transaction (currently available are: Normal
-Authorization, Authorization Only, Credit, Post Authorization,
-Recurring Authorization, Modify Recurring Authorization,
-Cancel Recurring Authorization)
+What action being taken by this transaction. Currently available are:
+
+=over 8
+
+=item Normal Authorization
+
+=item Authorization Only
+
+=item Post Authorization
+
+=item Void
+
+=item Credit
+
+=item Recurring Authorization
+
+=item Modify Recurring Authorization
+
+=item Cancel Recurring Authorization
+
+=back
 
 =item amount
 
@@ -678,9 +736,13 @@ Use this for handling boolean content like tax_exempt.
 
 =head1 AUTHORS
 
+(v2 series)
+
 Jason Kohles, email@jasonkohles.com
 
-(v3 rewrite) Ivan Kohler <ivan-business-onlinepayment@420.am>
+(v3 rewrite)
+
+Ivan Kohler <ivan-business-onlinepayment@420.am>
 
 Phil Lobbes E<lt>phil at perkpartners dot comE<gt>
 
diff --git a/notes_for_module_writers_v3 b/notes_for_module_writers_v3
index 7ce39b5..6b98a3b 100644
--- a/notes_for_module_writers_v3
+++ b/notes_for_module_writers_v3
@@ -38,4 +38,60 @@ These are the module writer's notes for v3.  See the regular
 
       (or add "failure_status" to your build_subs call if you have one during
       initialization)
-      
+
+
+- (NEW IN 3.01) Introspection:
+
+  - Add an _info subroutine to your module that returns a hashref of
+    information:
+
+      sub _info {
+        {
+          'info_compat'           => '0.01', # always 0.01 for now,
+                                             # 0.02 will have requirements
+          'gateway_name'          => 'Example Gateway',
+          'gateway_url'           => 'http://www.example.com/',
+          'module_version'        => $VERSION,
+          'supported_types'       => [ qw( CC ECHECK ) ],
+          'supported_actions'     => [
+                                       'Normal Authorization',
+                                       'Authorization Only',
+                                       'Post Authorization',
+                                       'Void',
+                                       'Credit',
+                                     ],
+        };
+      }
+
+    # or a more complicated case:
+
+      sub _info {
+        {
+          'info_compat'           => '0.01', # always 0.01 for now,
+                                             # 0.02 will have requirements
+          'gateway_name'          => 'Example Gateway',
+          'gateway_url'           => 'http://www.example.com/',
+          'module_version'        => $VERSION,
+          'module_notes'          => 'usage notes',
+          'supported_types'       => [ qw( CC ECHECK ) ],
+          'supported_actions'     => { 'CC' => [
+                                         'Normal Authorization',
+                                         'Authorization Only',
+                                         'Post Authorization',
+                                         'Void',
+                                         'Credit',
+                                         'Recurring Authorization',
+                                         'Modify Recurring Authorization',
+                                         'Cancel Recurring Authorization',
+                                       ],
+                                       'ECHECK' => [
+                                         'Normal Authorization',
+                                         'Void',
+                                         'Credit',
+                                       ],
+                                     },
+          'CC_void_requires_card' => 1,
+        };
+      }
+
+
-- 
2.11.0