hs-playlib 0.1.0 → 0.3.0

package/dist/src/payments/_generated_flows.js

@@ -3,24 +3,61 @@
 "use strict";
 
 const FLOWS = {
+  // authenticate: PaymentMethodAuthenticationService.Authenticate — Execute 3DS challenge or frictionless verification. Authenticates customer via bank challenge or behind-the-scenes verification for fraud prevention.
+  authenticate         : { request: "PaymentMethodAuthenticationServiceAuthenticateRequest", response: "PaymentMethodAuthenticationServiceAuthenticateResponse" },
+
   // authorize: PaymentService.Authorize — Authorize a payment amount on a payment method. This reserves funds without capturing them, essential for verifying availability before finalizing.
-  authorize           : { request: "PaymentServiceAuthorizeRequest", response: "PaymentServiceAuthorizeResponse" },
+  authorize            : { request: "PaymentServiceAuthorizeRequest", response: "PaymentServiceAuthorizeResponse" },
 
   // capture: PaymentService.Capture — Finalize an authorized payment transaction. Transfers reserved funds from customer to merchant account, completing the payment lifecycle.
-  capture             : { request: "PaymentServiceCaptureRequest", response: "PaymentServiceCaptureResponse" },
+  capture              : { request: "PaymentServiceCaptureRequest", response: "PaymentServiceCaptureResponse" },
+
+  // charge: RecurringPaymentService.Charge — Charge using an existing stored recurring payment instruction. Processes repeat payments for subscriptions or recurring billing without collecting payment details.
+  charge               : { request: "RecurringPaymentServiceChargeRequest", response: "RecurringPaymentServiceChargeResponse" },
+
+  // create: CustomerService.Create — Create customer record in the payment processor system. Stores customer details for future payment operations without re-sending personal information.
+  create               : { request: "CustomerServiceCreateRequest", response: "CustomerServiceCreateResponse" },
 
   // create_access_token: MerchantAuthenticationService.CreateAccessToken — Generate short-lived connector authentication token. Provides secure credentials for connector API access without storing secrets client-side.
-  create_access_token : { request: "MerchantAuthenticationServiceCreateAccessTokenRequest", response: "MerchantAuthenticationServiceCreateAccessTokenResponse" },
+  create_access_token  : { request: "MerchantAuthenticationServiceCreateAccessTokenRequest", response: "MerchantAuthenticationServiceCreateAccessTokenResponse" },
+
+  // create_order: PaymentService.CreateOrder — Initialize an order in the payment processor system. Sets up payment context before customer enters card details for improved authorization rates.
+  create_order         : { request: "PaymentServiceCreateOrderRequest", response: "PaymentServiceCreateOrderResponse" },
+
+  // create_session_token: MerchantAuthenticationService.CreateSessionToken — Create session token for payment processing. Maintains session state across multiple payment operations for improved security and tracking.
+  create_session_token : { request: "MerchantAuthenticationServiceCreateSessionTokenRequest", response: "MerchantAuthenticationServiceCreateSessionTokenResponse" },
 
   // get: PaymentService.Get — Retrieve current payment status from the payment processor. Enables synchronization between your system and payment processors for accurate state tracking.
-  get                 : { request: "PaymentServiceGetRequest", response: "PaymentServiceGetResponse" },
+  get                  : { request: "PaymentServiceGetRequest", response: "PaymentServiceGetResponse" },
+
+  // post_authenticate: PaymentMethodAuthenticationService.PostAuthenticate — Validate authentication results with the issuing bank. Processes bank's authentication decision to determine if payment can proceed.
+  post_authenticate    : { request: "PaymentMethodAuthenticationServicePostAuthenticateRequest", response: "PaymentMethodAuthenticationServicePostAuthenticateResponse" },
+
+  // pre_authenticate: PaymentMethodAuthenticationService.PreAuthenticate — Initiate 3DS flow before payment authorization. Collects device data and prepares authentication context for frictionless or challenge-based verification.
+  pre_authenticate     : { request: "PaymentMethodAuthenticationServicePreAuthenticateRequest", response: "PaymentMethodAuthenticationServicePreAuthenticateResponse" },
 
   // refund: PaymentService.Refund — Initiate a refund to customer's payment method. Returns funds for returns, cancellations, or service adjustments after original payment.
-  refund              : { request: "PaymentServiceRefundRequest", response: "RefundResponse" },
+  refund               : { request: "PaymentServiceRefundRequest", response: "RefundResponse" },
+
+  // reverse: PaymentService.Reverse — Reverse a captured payment before settlement. Recovers funds after capture but before bank settlement, used for corrections or cancellations.
+  reverse              : { request: "PaymentServiceReverseRequest", response: "PaymentServiceReverseResponse" },
+
+  // setup_recurring: PaymentService.SetupRecurring — Setup a recurring payment instruction for future payments/ debits. This could be for SaaS subscriptions, monthly bill payments, insurance payments and similar use cases.
+  setup_recurring      : { request: "PaymentServiceSetupRecurringRequest", response: "PaymentServiceSetupRecurringResponse" },
+
+  // tokenize: PaymentMethodService.Tokenize — Tokenize payment method for secure storage. Replaces raw card details with secure token for one-click payments and recurring billing.
+  tokenize             : { request: "PaymentMethodServiceTokenizeRequest", response: "PaymentMethodServiceTokenizeResponse" },
 
   // void: PaymentService.Void — Cancel an authorized payment before capture. Releases held funds back to customer, typically used when orders are cancelled or abandoned.
-  void                : { request: "PaymentServiceVoidRequest", response: "PaymentServiceVoidResponse" },
+  void                 : { request: "PaymentServiceVoidRequest", response: "PaymentServiceVoidResponse" },
+
+};
+
+// Single-step flows: no HTTP round-trip.
+const SINGLE_FLOWS = {
+  // handle_event: EventService.HandleEvent — Process webhook notifications from connectors. Translates connector events into standardized responses for asynchronous payment state updates.
+  handle_event : { request: "EventServiceHandleRequest", response: "EventServiceHandleResponse" },
 
 };
 
-module.exports = { FLOWS };
+module.exports = { FLOWS, SINGLE_FLOWS };

package/dist/src/payments/_generated_uniffi_client_flows.d.ts

@@ -1,27 +1,69 @@
 import { UniffiClient as _UniffiClientBase } from "./uniffi_client";
 export declare class UniffiClient extends _UniffiClientBase {
+    /** Build connector HTTP request for authenticate flow. */
+    authenticateReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Parse connector HTTP response for authenticate flow. */
+    authenticateRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
     /** Build connector HTTP request for authorize flow. */
-    authorizeReq(requestBytes: Buffer | Uint8Array, metadata: Record<string, string>, optionsBytes: Buffer | Uint8Array): Buffer;
+    authorizeReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
     /** Parse connector HTTP response for authorize flow. */
-    authorizeRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, metadata: Record<string, string>, optionsBytes: Buffer | Uint8Array): Buffer;
+    authorizeRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
     /** Build connector HTTP request for capture flow. */
-    captureReq(requestBytes: Buffer | Uint8Array, metadata: Record<string, string>, optionsBytes: Buffer | Uint8Array): Buffer;
+    captureReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
     /** Parse connector HTTP response for capture flow. */
-    captureRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, metadata: Record<string, string>, optionsBytes: Buffer | Uint8Array): Buffer;
+    captureRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Build connector HTTP request for charge flow. */
+    chargeReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Parse connector HTTP response for charge flow. */
+    chargeRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Build connector HTTP request for create flow. */
+    createReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Parse connector HTTP response for create flow. */
+    createRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
     /** Build connector HTTP request for create_access_token flow. */
-    createAccessTokenReq(requestBytes: Buffer | Uint8Array, metadata: Record<string, string>, optionsBytes: Buffer | Uint8Array): Buffer;
+    createAccessTokenReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
     /** Parse connector HTTP response for create_access_token flow. */
-    createAccessTokenRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, metadata: Record<string, string>, optionsBytes: Buffer | Uint8Array): Buffer;
+    createAccessTokenRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Build connector HTTP request for create_order flow. */
+    createOrderReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Parse connector HTTP response for create_order flow. */
+    createOrderRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Build connector HTTP request for create_session_token flow. */
+    createSessionTokenReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Parse connector HTTP response for create_session_token flow. */
+    createSessionTokenRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
     /** Build connector HTTP request for get flow. */
-    getReq(requestBytes: Buffer | Uint8Array, metadata: Record<string, string>, optionsBytes: Buffer | Uint8Array): Buffer;
+    getReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
     /** Parse connector HTTP response for get flow. */
-    getRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, metadata: Record<string, string>, optionsBytes: Buffer | Uint8Array): Buffer;
+    getRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Build connector HTTP request for post_authenticate flow. */
+    postAuthenticateReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Parse connector HTTP response for post_authenticate flow. */
+    postAuthenticateRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Build connector HTTP request for pre_authenticate flow. */
+    preAuthenticateReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Parse connector HTTP response for pre_authenticate flow. */
+    preAuthenticateRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
     /** Build connector HTTP request for refund flow. */
-    refundReq(requestBytes: Buffer | Uint8Array, metadata: Record<string, string>, optionsBytes: Buffer | Uint8Array): Buffer;
+    refundReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
     /** Parse connector HTTP response for refund flow. */
-    refundRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, metadata: Record<string, string>, optionsBytes: Buffer | Uint8Array): Buffer;
+    refundRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Build connector HTTP request for reverse flow. */
+    reverseReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Parse connector HTTP response for reverse flow. */
+    reverseRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Build connector HTTP request for setup_recurring flow. */
+    setupRecurringReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Parse connector HTTP response for setup_recurring flow. */
+    setupRecurringRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Build connector HTTP request for tokenize flow. */
+    tokenizeReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Parse connector HTTP response for tokenize flow. */
+    tokenizeRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
     /** Build connector HTTP request for void flow. */
-    voidReq(requestBytes: Buffer | Uint8Array, metadata: Record<string, string>, optionsBytes: Buffer | Uint8Array): Buffer;
+    voidReq(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
     /** Parse connector HTTP response for void flow. */
-    voidRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, metadata: Record<string, string>, optionsBytes: Buffer | Uint8Array): Buffer;
+    voidRes(responseBytes: Buffer | Uint8Array, requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
+    /** Direct single-step transform for handle_event (no HTTP round-trip). */
+    handleEventDirect(requestBytes: Buffer | Uint8Array, optionsBytes: Buffer | Uint8Array): Buffer;
 }

package/dist/src/payments/_generated_uniffi_client_flows.js

@@ -5,53 +5,137 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.UniffiClient = void 0;
 const uniffi_client_1 = require("./uniffi_client");
 class UniffiClient extends uniffi_client_1.UniffiClient {
+    /** Build connector HTTP request for authenticate flow. */
+    authenticateReq(requestBytes, optionsBytes) {
+        return this.callReq('authenticate', requestBytes, optionsBytes);
+    }
+    /** Parse connector HTTP response for authenticate flow. */
+    authenticateRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('authenticate', responseBytes, requestBytes, optionsBytes);
+    }
     /** Build connector HTTP request for authorize flow. */
-    authorizeReq(requestBytes, metadata, optionsBytes) {
-        return this.callReq('authorize', requestBytes, metadata, optionsBytes);
+    authorizeReq(requestBytes, optionsBytes) {
+        return this.callReq('authorize', requestBytes, optionsBytes);
     }
     /** Parse connector HTTP response for authorize flow. */
-    authorizeRes(responseBytes, requestBytes, metadata, optionsBytes) {
-        return this.callRes('authorize', responseBytes, requestBytes, metadata, optionsBytes);
+    authorizeRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('authorize', responseBytes, requestBytes, optionsBytes);
     }
     /** Build connector HTTP request for capture flow. */
-    captureReq(requestBytes, metadata, optionsBytes) {
-        return this.callReq('capture', requestBytes, metadata, optionsBytes);
+    captureReq(requestBytes, optionsBytes) {
+        return this.callReq('capture', requestBytes, optionsBytes);
     }
     /** Parse connector HTTP response for capture flow. */
-    captureRes(responseBytes, requestBytes, metadata, optionsBytes) {
-        return this.callRes('capture', responseBytes, requestBytes, metadata, optionsBytes);
+    captureRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('capture', responseBytes, requestBytes, optionsBytes);
+    }
+    /** Build connector HTTP request for charge flow. */
+    chargeReq(requestBytes, optionsBytes) {
+        return this.callReq('charge', requestBytes, optionsBytes);
+    }
+    /** Parse connector HTTP response for charge flow. */
+    chargeRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('charge', responseBytes, requestBytes, optionsBytes);
+    }
+    /** Build connector HTTP request for create flow. */
+    createReq(requestBytes, optionsBytes) {
+        return this.callReq('create', requestBytes, optionsBytes);
+    }
+    /** Parse connector HTTP response for create flow. */
+    createRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('create', responseBytes, requestBytes, optionsBytes);
     }
     /** Build connector HTTP request for create_access_token flow. */
-    createAccessTokenReq(requestBytes, metadata, optionsBytes) {
-        return this.callReq('create_access_token', requestBytes, metadata, optionsBytes);
+    createAccessTokenReq(requestBytes, optionsBytes) {
+        return this.callReq('create_access_token', requestBytes, optionsBytes);
     }
     /** Parse connector HTTP response for create_access_token flow. */
-    createAccessTokenRes(responseBytes, requestBytes, metadata, optionsBytes) {
-        return this.callRes('create_access_token', responseBytes, requestBytes, metadata, optionsBytes);
+    createAccessTokenRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('create_access_token', responseBytes, requestBytes, optionsBytes);
+    }
+    /** Build connector HTTP request for create_order flow. */
+    createOrderReq(requestBytes, optionsBytes) {
+        return this.callReq('create_order', requestBytes, optionsBytes);
+    }
+    /** Parse connector HTTP response for create_order flow. */
+    createOrderRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('create_order', responseBytes, requestBytes, optionsBytes);
+    }
+    /** Build connector HTTP request for create_session_token flow. */
+    createSessionTokenReq(requestBytes, optionsBytes) {
+        return this.callReq('create_session_token', requestBytes, optionsBytes);
+    }
+    /** Parse connector HTTP response for create_session_token flow. */
+    createSessionTokenRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('create_session_token', responseBytes, requestBytes, optionsBytes);
     }
     /** Build connector HTTP request for get flow. */
-    getReq(requestBytes, metadata, optionsBytes) {
-        return this.callReq('get', requestBytes, metadata, optionsBytes);
+    getReq(requestBytes, optionsBytes) {
+        return this.callReq('get', requestBytes, optionsBytes);
     }
     /** Parse connector HTTP response for get flow. */
-    getRes(responseBytes, requestBytes, metadata, optionsBytes) {
-        return this.callRes('get', responseBytes, requestBytes, metadata, optionsBytes);
+    getRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('get', responseBytes, requestBytes, optionsBytes);
+    }
+    /** Build connector HTTP request for post_authenticate flow. */
+    postAuthenticateReq(requestBytes, optionsBytes) {
+        return this.callReq('post_authenticate', requestBytes, optionsBytes);
+    }
+    /** Parse connector HTTP response for post_authenticate flow. */
+    postAuthenticateRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('post_authenticate', responseBytes, requestBytes, optionsBytes);
+    }
+    /** Build connector HTTP request for pre_authenticate flow. */
+    preAuthenticateReq(requestBytes, optionsBytes) {
+        return this.callReq('pre_authenticate', requestBytes, optionsBytes);
+    }
+    /** Parse connector HTTP response for pre_authenticate flow. */
+    preAuthenticateRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('pre_authenticate', responseBytes, requestBytes, optionsBytes);
     }
     /** Build connector HTTP request for refund flow. */
-    refundReq(requestBytes, metadata, optionsBytes) {
-        return this.callReq('refund', requestBytes, metadata, optionsBytes);
+    refundReq(requestBytes, optionsBytes) {
+        return this.callReq('refund', requestBytes, optionsBytes);
     }
     /** Parse connector HTTP response for refund flow. */
-    refundRes(responseBytes, requestBytes, metadata, optionsBytes) {
-        return this.callRes('refund', responseBytes, requestBytes, metadata, optionsBytes);
+    refundRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('refund', responseBytes, requestBytes, optionsBytes);
+    }
+    /** Build connector HTTP request for reverse flow. */
+    reverseReq(requestBytes, optionsBytes) {
+        return this.callReq('reverse', requestBytes, optionsBytes);
+    }
+    /** Parse connector HTTP response for reverse flow. */
+    reverseRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('reverse', responseBytes, requestBytes, optionsBytes);
+    }
+    /** Build connector HTTP request for setup_recurring flow. */
+    setupRecurringReq(requestBytes, optionsBytes) {
+        return this.callReq('setup_recurring', requestBytes, optionsBytes);
+    }
+    /** Parse connector HTTP response for setup_recurring flow. */
+    setupRecurringRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('setup_recurring', responseBytes, requestBytes, optionsBytes);
+    }
+    /** Build connector HTTP request for tokenize flow. */
+    tokenizeReq(requestBytes, optionsBytes) {
+        return this.callReq('tokenize', requestBytes, optionsBytes);
+    }
+    /** Parse connector HTTP response for tokenize flow. */
+    tokenizeRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('tokenize', responseBytes, requestBytes, optionsBytes);
     }
     /** Build connector HTTP request for void flow. */
-    voidReq(requestBytes, metadata, optionsBytes) {
-        return this.callReq('void', requestBytes, metadata, optionsBytes);
+    voidReq(requestBytes, optionsBytes) {
+        return this.callReq('void', requestBytes, optionsBytes);
     }
     /** Parse connector HTTP response for void flow. */
-    voidRes(responseBytes, requestBytes, metadata, optionsBytes) {
-        return this.callRes('void', responseBytes, requestBytes, metadata, optionsBytes);
+    voidRes(responseBytes, requestBytes, optionsBytes) {
+        return this.callRes('void', responseBytes, requestBytes, optionsBytes);
+    }
+    /** Direct single-step transform for handle_event (no HTTP round-trip). */
+    handleEventDirect(requestBytes, optionsBytes) {
+        return this.callDirect('handle_event', requestBytes, optionsBytes);
     }
 }
 exports.UniffiClient = UniffiClient;

package/dist/src/payments/connector_client.d.ts

@@ -9,33 +9,37 @@
  *   5. Deserialize protobuf response from bytes
  *
  * Flow methods (authorize, capture, void, refund, …) are in _generated_connector_client_flows.ts.
- * To add a new flow: implement it in the FFI crate and run `make generate`.
+ * To add a new flow: edit sdk/flows.yaml and run `make codegen`.
  */
-import { ucs } from "./generated/proto";
+import { types } from "./generated/proto";
 export declare class ConnectorClient {
     private uniffi;
-    private options;
+    private config;
+    private defaults;
     private dispatcher;
     /**
-     * @param libPath - optional path to the UniFFI shared library
-     * @param options - unified SDK configuration from Protobuf (Options message)
+     * Initialize the client with mandatory config and optional request defaults.
+     *
+     * @param config - Immutable connector identity and environment (Connector, Auth, Environment).
+     * @param defaults - Optional per-request defaults (Http, Vault).
+     * @param libPath - optional path to the UniFFI shared library.
      */
-    constructor(libPath?: string, options?: ucs.v2.IOptions);
+    constructor(config: types.IConnectorConfig, defaults?: types.IRequestConfig, libPath?: string);
     /**
-     * Internal helper to map Protobuf HttpOptions to Native HttpClient options.
+     * Merges request-level options with client defaults. Environment comes from config (immutable).
      */
-    private getNativeHttpOptions;
+    private _resolveConfig;
     /**
      * Execute a full round-trip for any registered payment flow.
      *
-     * Looks up the request/response protobuf type names from FLOWS, encodes the
-     * request, calls callReq → HTTP → callRes via the generic FFI dispatcher,
-     * then decodes and returns the response.
-     *
      * @param flow - Flow name matching the FFI transformer prefix (e.g. "authorize").
      * @param requestMsg - Protobuf request message object.
-     * @param metadata - Dict with connector routing and auth info.
-     * @param ffiOptions - Optional IFfiOptions override.
+     * @param options - Optional ConfigOptions override (Environment, Http).
+     */
+    _executeFlow(flow: string, requestMsg: object, options?: types.IRequestConfig | null, reqTypeName?: string, resTypeName?: string): Promise<unknown>;
+    /**
+     * Execute a single-step flow directly via FFI (no HTTP round-trip).
+     * Used for inbound flows like webhook processing where the connector sends data to us.
      */
-    _executeFlow(flow: string, requestMsg: object, metadata: Record<string, string>, ffiOptions?: ucs.v2.IFfiOptions | null, reqTypeName?: string, resTypeName?: string): Promise<unknown>;
+    _executeDirect(flow: string, requestMsg: object, options?: types.IRequestConfig | null, reqTypeName?: string, resTypeName?: string): Promise<unknown>;
 }

package/dist/src/payments/connector_client.js

@@ -10,7 +10,7 @@
  *   5. Deserialize protobuf response from bytes
  *
  * Flow methods (authorize, capture, void, refund, …) are in _generated_connector_client_flows.ts.
- * To add a new flow: implement it in the FFI crate and run `make generate`.
+ * To add a new flow: edit sdk/flows.yaml and run `make codegen`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConnectorClient = void 0;
@@ -18,65 +18,71 @@ const uniffi_client_1 = require("./uniffi_client");
 const http_client_1 = require("../http_client");
 // @ts-ignore - protobuf generated files might not have types yet
 const proto_1 = require("./generated/proto");
-const v2 = proto_1.ucs.v2;
+const v2 = proto_1.types;
 class ConnectorClient {
     uniffi;
-    options;
+    config;
+    defaults;
     dispatcher;
     /**
-     * @param libPath - optional path to the UniFFI shared library
-     * @param options - unified SDK configuration from Protobuf (Options message)
+     * Initialize the client with mandatory config and optional request defaults.
+     *
+     * @param config - Immutable connector identity and environment (Connector, Auth, Environment).
+     * @param defaults - Optional per-request defaults (Http, Vault).
+     * @param libPath - optional path to the UniFFI shared library.
      */
-    constructor(libPath, options = {}) {
+    constructor(config, defaults = {}, libPath) {
         this.uniffi = new uniffi_client_1.UniffiClient(libPath);
-        this.options = options;
+        this.config = proto_1.types.ConnectorConfig.create(config);
+        this.defaults = defaults;
+        if (config.connector === undefined) {
+            throw new http_client_1.ConnectorError("Connector is required in ConnectorConfig", 400, "CLIENT_INITIALIZATION");
+        }
         // Instance-level cache: create the primary connection pool at startup
-        this.dispatcher = (0, http_client_1.createDispatcher)(this.getNativeHttpOptions(options.http));
+        this.dispatcher = (0, http_client_1.createDispatcher)(defaults.http || {});
     }
     /**
-     * Internal helper to map Protobuf HttpOptions to Native HttpClient options.
+     * Merges request-level options with client defaults. Environment comes from config (immutable).
      */
-    getNativeHttpOptions(proto) {
-        if (!proto)
-            return {};
-        return {
-            totalTimeoutMs: proto.totalTimeoutMs ?? undefined,
-            connectTimeoutMs: proto.connectTimeoutMs ?? undefined,
-            responseTimeoutMs: proto.responseTimeoutMs ?? undefined,
-            keepAliveTimeoutMs: proto.keepAliveTimeoutMs ?? undefined,
-            proxy: proto.proxy ? {
-                httpUrl: proto.proxy.httpUrl ?? undefined,
-                httpsUrl: proto.proxy.httpsUrl ?? undefined,
-                bypassUrls: proto.proxy.bypassUrls ?? undefined,
-            } : undefined,
-            caCert: proto.caCert ?? undefined,
+    _resolveConfig(overrides) {
+        const opt = overrides || {};
+        const clientHttp = this.defaults.http || {};
+        const overrideHttp = opt.http || {};
+        const http = {
+            totalTimeoutMs: overrideHttp.totalTimeoutMs ?? clientHttp.totalTimeoutMs,
+            connectTimeoutMs: overrideHttp.connectTimeoutMs ?? clientHttp.connectTimeoutMs,
+            responseTimeoutMs: overrideHttp.responseTimeoutMs ?? clientHttp.responseTimeoutMs,
+            keepAliveTimeoutMs: overrideHttp.keepAliveTimeoutMs ?? clientHttp.keepAliveTimeoutMs,
+            proxy: overrideHttp.proxy ?? clientHttp.proxy,
+            caCert: overrideHttp.caCert ?? clientHttp.caCert,
         };
+        const ffi = proto_1.types.FfiOptions.create({
+            environment: this.config.environment ?? proto_1.types.Environment.SANDBOX,
+            connector: this.config.connector,
+            auth: this.config.auth,
+        });
+        return { ffi, http };
     }
     /**
      * Execute a full round-trip for any registered payment flow.
      *
-     * Looks up the request/response protobuf type names from FLOWS, encodes the
-     * request, calls callReq → HTTP → callRes via the generic FFI dispatcher,
-     * then decodes and returns the response.
-     *
      * @param flow - Flow name matching the FFI transformer prefix (e.g. "authorize").
      * @param requestMsg - Protobuf request message object.
-     * @param metadata - Dict with connector routing and auth info.
-     * @param ffiOptions - Optional IFfiOptions override.
+     * @param options - Optional ConfigOptions override (Environment, Http).
      */
-    async _executeFlow(flow, requestMsg, metadata, ffiOptions, reqTypeName, resTypeName) {
+    async _executeFlow(flow, requestMsg, options, reqTypeName, resTypeName) {
         const reqType = reqTypeName ? v2[reqTypeName] : undefined;
         const resType = resTypeName ? v2[resTypeName] : undefined;
         if (!reqType || !resType) {
             throw new Error(`Unknown flow: '${flow}' or missing type names.`);
         }
-        // 1. Serialize request
+        // 1. Resolve final configuration
+        const { ffi, http } = this._resolveConfig(options);
+        const optionsBytes = Buffer.from(v2.FfiOptions.encode(ffi).finish());
+        // 2. Serialize domain request
         const requestBytes = Buffer.from(reqType.encode(requestMsg).finish());
-        // 2. Resolve FFI options (prefer call-specific)
-        const ffi = ffiOptions || this.options.ffi;
-        const optionsBytes = ffi ? Buffer.from(v2.FfiOptions.encode(ffi).finish()) : Buffer.alloc(0);
-        // 3. Build connector HTTP request via FFI (returns FfiConnectorHttpRequest protobuf bytes)
-        const resultBytes = this.uniffi.callReq(flow, requestBytes, metadata, optionsBytes);
+        // 3. Build connector HTTP request via FFI
+        const resultBytes = this.uniffi.callReq(flow, requestBytes, optionsBytes);
         const connectorReq = v2.FfiConnectorHttpRequest.decode(resultBytes);
         const connectorRequest = {
             url: connectorReq.url,
@@ -85,8 +91,8 @@ class ConnectorClient {
             body: connectorReq.body ?? undefined
         };
         // 4. Execute HTTP using the instance-owned connection pool
-        const response = await (0, http_client_1.execute)(connectorRequest, this.getNativeHttpOptions(this.options.http), this.dispatcher);
-        // 5. Encode HTTP response as FfiConnectorHttpResponse protobuf bytes
+        const response = await (0, http_client_1.execute)(connectorRequest, http, this.dispatcher);
+        // 5. Encode HTTP response for FFI
         const resProto = v2.FfiConnectorHttpResponse.create({
             statusCode: response.statusCode,
             headers: response.headers,
@@ -94,9 +100,28 @@ class ConnectorClient {
         });
         const resBytes = Buffer.from(v2.FfiConnectorHttpResponse.encode(resProto).finish());
         // 6. Parse connector response via FFI and decode
-        const resultBytesRes = this.uniffi.callRes(flow, resBytes, requestBytes, metadata, optionsBytes);
+        const resultBytesRes = this.uniffi.callRes(flow, resBytes, requestBytes, optionsBytes);
         return resType.decode(resultBytesRes);
     }
+    /**
+     * Execute a single-step flow directly via FFI (no HTTP round-trip).
+     * Used for inbound flows like webhook processing where the connector sends data to us.
+     */
+    async _executeDirect(flow, requestMsg, options, reqTypeName, resTypeName) {
+        const reqType = reqTypeName ? v2[reqTypeName] : undefined;
+        const resType = resTypeName ? v2[resTypeName] : undefined;
+        if (!reqType || !resType) {
+            throw new Error(`Unknown flow: '${flow}' or missing type names.`);
+        }
+        // 1. Serialize request
+        const requestBytes = Buffer.from(reqType.encode(requestMsg).finish());
+        // 2. Resolve FFI options from identity + defaults + request override
+        const { ffi } = this._resolveConfig(options);
+        const optionsBytes = Buffer.from(v2.FfiOptions.encode(ffi).finish());
+        // 3. Call the single-step transformer directly (no HTTP)
+        const resultBytes = this.uniffi.callDirect(flow, requestBytes, optionsBytes);
+        return resType.decode(resultBytes);
+    }
 }
 exports.ConnectorClient = ConnectorClient;
 //# sourceMappingURL=connector_client.js.map