@payabli/component-contracts 0.2.0 → 0.4.0

package/README.md

@@ -14,7 +14,7 @@ pnpm add @payabli/component-contracts
 
 - `protocol/`: the postMessage envelope, `parseEnvelope` / `parseMessage` /
   `parsePayload`, the base events every component emits, and the messages the
-  SDK sends to the iframe (`CONFIG_SET`, `SESSION_UPDATE`, `SUBMIT`, ...).
+  SDK sends to the iframe (`CONFIG_SET`, `SUBMIT_REQUEST`, ...).
 - `payin/`: the PayIn component. Its options schema, event schemas, and the
   `PAYMENT_METHODS` / `CARD_BRANDS` vocabulary.
 - `registry`: `register()`, `getComponentDescriptor()`, and the
@@ -33,7 +33,7 @@ Prefill remains a generic capability that other components may support through `
 ### Session/init config
 
 The request is `POST /api/v2/{slug}/Session/init` with `platform: 'Web'`, `entryPoint`, `allowedParentOrigins`, and `components`.
-`GET /api/v2/Session/bootstrap` returns each component's config unchanged.
+The iframe gets each component's config unchanged from the server session.
 Tenant identity, operation, payment amounts, customer data, and invoice data come only from the server session.
 The browser submit payload contains payment credentials, capture results, and the selected method, not business configuration.
 
@@ -303,12 +303,12 @@ The exported `FORM_METHODS` tuple defines the default order.
 Without overrides, the default order and initial method stay unchanged.
 The options schema rejects unknown method names and non-array orders. It accepts duplicates for the iframe to ignore.
 The SDK forwards options unchanged through `CONFIG_SET.options`. React uses the existing `options` prop, with no new props.
-`payin.update({ options: { initialMethod: 'card', methodOrder: ['card', 'ach'] } })` remounts the iframe.
+`payin.update({ options: { initialMethod: 'card', methodOrder: ['card', 'ach'] } })` sends `CONFIG_SET` to the live frame. The frame stays in place.
 No new session is required. Layout, density, label style, and color scheme are unchanged.
 
 ### Appearance
 
-`appearance` is client-side. `update()` remounts the iframe without creating a new session.
+`appearance` is client-side. `update()` applies it to the live frame without a new session. `locale` is part of the frame URL, so `update()` does not change it on a live frame.
 
 | Setting             | Values and behavior                                                                                          |
 | ------------------- | ------------------------------------------------------------------------------------------------------------ |
@@ -386,16 +386,26 @@ const payin = payabli.create('payin', {
 #### Success and errors
 
 `success` and React's `onSuccess` report confirmed success only. `submit()` resolves with the same result data.
-`PayInSuccessPayload.transactionId` identifies a pay or auth transaction when present.
-The wire success data remains an open record. The SDK preserves fields it does not interpret.
 
-For tokenize sessions, `SUBMIT_RESULT.data`, the `success` event, and the `submit()` result contain:
+> [!IMPORTANT]
+> Confirm every outcome on your server with a webhook or a status call before you fulfill an order.
+> Do not use the browser `success` event alone as proof of payment. Code on the page can fake it.
+
+The payload is `PayInSuccessPayload`, one closed shape for every operation:
 
 ```ts
-{ referenceId: string, customerId?: number, methodReferenceId?: string }
+{
+  operation: 'pay' | 'auth' | 'tokenize',
+  method: 'card' | 'ach' | 'check' | 'applepay' | 'googlepay',
+  transactionId?: string,   // pay, auth
+  storedMethodId?: string,  // tokenize; pay or auth that saved the method
+  customerId?: number,      // when the API created or matched a customer
+  paymentMethod?: { maskedAccount?, accountType?, expiration?, holderName? },
+  amount?: { total: number, serviceFee?: number, currency?: string }, // pay, auth
+}
 ```
 
-`referenceId` is the saved payment method ID, not a transaction ID. `PayInSuccessPayload` declares it as an optional string.
+`transactionId` is the Payabli transaction id. `storedMethodId` is the saved payment method id: pass it back as `storedMethodId` on a later payment. The API response body does not reach the page.
 
 A failed `SUBMIT_RESULT` rejects `submit()` and emits `error`, mapped to React's `onError`.
 Errors have `{ code, message, recoverable, details? }`. The SDK forwards the code and message unchanged.
@@ -407,7 +417,7 @@ Recoverable failures release the lock. Non-recoverable failures keep it locked.
 | ------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | `SUBMIT_FAILED`           | Confirmed decline or validation failure. Keep entered values and allow correction when `recoverable: true`. |
 | `OUTCOME_UNKNOWN`         | The API did not confirm the result. A prior attempt may have processed. Do not retry this session.          |
-| `SESSION_COMPLETED`       | The session already succeeded. Create a new session.                                                        |
+| `SESSION_COMPLETED`       | This component already succeeded. The SDK emits `error` and removes this component.                         |
 | `UNSUPPORTED_OPERATION`   | The session operation does not support this method. No payment API call occurs.                             |
 | `UNSUPPORTED_SAVE_METHOD` | Check cannot use `saveIfSuccess: true`. No payment API call occurs.                                         |
 
@@ -441,16 +451,25 @@ In React, read `isValid` from `onChange`. Do not use `onReady` or `onRendered` a
 
 #### SDK and session errors
 
-| Code                     | Meaning and recovery                                                                                      |
-| ------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `LOAD_TIMEOUT`           | The iframe did not send READY within the timeout. The SDK retries loading once before reporting an error. |
-| `PROTOCOL_ERROR`         | postMessage validation failed.                                                                            |
-| `INVALID_STATE`          | The operation targets a destroyed instance.                                                               |
-| `SESSION_EXPIRED`        | The session reached its ceiling or refresh failed without recovery. Supply a new session.                 |
-| `SESSION_REFRESH_FAILED` | An individual auto-refresh attempt failed and is recoverable.                                             |
-| `TOKEN_EXPIRED`          | An iframe API call used an expired JWT. The SDK refreshes immediately without a public event.             |
-| `RENDER_TOKEN_EXPIRED`   | The frame URL no longer renders. The SDK rebuilds the frame and reports an error after the rebuild limit. |
-| `RENDER_TOKEN_INVALID`   | Render token signature, audience, or format checks failed. Global `sessionError` requires a new session.  |
+| Code                    | Meaning and recovery                                                                                                                                                     |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `LOAD_TIMEOUT`          | The iframe did not send READY within the timeout. The SDK retries loading once before reporting an error.                                                                |
+| `PROTOCOL_ERROR`        | postMessage validation failed.                                                                                                                                           |
+| `INVALID_STATE`         | The operation targets a destroyed instance.                                                                                                                              |
+| `EXCHANGE_CODE_INVALID` | The frame could not redeem its exchange code: unknown, expired, used, or issued for another key. The SDK emits `error` and removes this component. Create a new session. |
+
+Session errors go to `payabli.on('sessionExpired')` or `payabli.on('sessionError')`, not to the component `error` event.
+
+| Code                         | Event            | SDK action and recovery                                                                                  |
+| ---------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------- |
+| `SESSION_EXPIRED`            | `sessionExpired` | Removes every frame. Create a new session and mount again.                                               |
+| `RENDER_TOKEN_EXPIRED`       | `sessionExpired` | Removes every frame. The render token ends at the session ceiling. Create a new session and mount again. |
+| `SESSION_REVOKED`            | `sessionError`   | Removes every frame. Create a new session and mount again.                                               |
+| `SESSION_COOKIE_UNAVAILABLE` | `sessionError`   | Removes every frame. The browser did not return the session cookie to the frame.                         |
+| `SESSION_LIMIT_REACHED`      | `sessionError`   | Removes every frame. Create a new session.                                                               |
+| `SESSION_INVALID`            | `sessionError`   | Removes every frame. Create a new session.                                                               |
+| `ORIGIN_NOT_ALLOWED`         | `sessionError`   | Removes every frame. Add the page origin to `allowedParentOrigins` and create a new session.             |
+| `RENDER_TOKEN_INVALID`       | `sessionError`   | Removes every frame. Render token signature, audience, or format checks failed. Create a new session.    |
 
 ### Post-success lock and session replacement
 
@@ -466,14 +485,13 @@ After success, the component clears sensitive payment fields and locks all field
 Repeated submissions return `SESSION_COMPLETED` with `recoverable: false`.
 Both error codes pass unchanged to the `submit()` rejection and the `error` event, or React's `onError` callback.
 
-Call `payabli.updateSession(newSession)` with a newly created session to unlock the component.
-This sends `SESSION_UPDATE` with `replace: true`. A token refresh with `replace: false` does not unlock it.
+Completion is per component key. After a successful PayIn submit, the SDK emits `success` and then removes only that PayIn component. Other components of the session stay usable, including another PayIn with a different key.
+Render the next state of your page in the `success` handler. To take another payment, create a new session and a new `Payabli` instance.
 
 Wallet sheets and form submission share one in-flight lock. Closing a wallet sheet releases it.
 After success, the iframe clears card number, CVV, expiration, account number, routing number, and check capture.
 The server records session completion and rejects later submissions before any payment API call.
-A new bootstrap session ID also remounts the form with fresh state and the new session key.
-Appearance updates and token refreshes do not clear the server completion lock.
+Appearance updates do not clear the server completion lock.
 
 The server stores attempt counters and completion records in Redis for the session lifetime. If Redis is unavailable, submission fails closed.
 GetPaid and Authorize cache each idempotency key for two minutes before processing, regardless of the result.
@@ -513,7 +531,7 @@ This is a pre-production breaking change. Remove obsolete configuration instead
 | Field label and placeholder text                              | Browser `appearance.labels` using the keys above.                                               |
 | `appearance.mode`                                             | `appearance.colorScheme`.                                                                       |
 | Ready-means-valid behavior                                    | Use `change.isValid` or React `onChange`. `ready` and `rendered` are lifecycle events.          |
-| Repeated submit after success                                 | Create a new session and call `payabli.updateSession(newSession)`.                              |
+| Repeated submit after success                                 | Create a new session and a new `Payabli` instance.                                              |
 
 Pay and auth examples must supply non-null `customerData`. Use identifiers that match the paypoint's customer rules.
 An empty object passes session validation but does not guarantee that the payment API can resolve a customer.

package/dist/errors.d.ts

@@ -8,26 +8,23 @@ export declare const ErrorCodes: {
     readonly OUTCOME_UNKNOWN: "OUTCOME_UNKNOWN";
     /** This session already completed an operation. Create a new session. */
     readonly SESSION_COMPLETED: "SESSION_COMPLETED";
+    /** The session reached its expiration ceiling. Create a new session and mount again. */
     readonly SESSION_EXPIRED: "SESSION_EXPIRED";
-    readonly SESSION_REFRESH_FAILED: "SESSION_REFRESH_FAILED";
-    /** Reported by an iframe whose call was rejected for an expired JWT. Triggers a refresh. */
-    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
-    /**
-     * Reported by an iframe whose render token no longer renders. The SDK recreates the frame
-     * with the latest render token.
-     */
+    /** The session was revoked. Terminal. */
+    readonly SESSION_REVOKED: "SESSION_REVOKED";
+    /** The session reached its expiration ceiling on the server. Terminal. */
+    readonly SESSION_LIMIT_REACHED: "SESSION_LIMIT_REACHED";
+    /** Unknown session, or one that names a component this API build lacks. Terminal. */
+    readonly SESSION_INVALID: "SESSION_INVALID";
+    /** The browser did not send the session cookie back to the frame. Terminal. */
+    readonly SESSION_COOKIE_UNAVAILABLE: "SESSION_COOKIE_UNAVAILABLE";
+    /** The exchange code is unknown, expired, already used, or issued for another key. */
+    readonly EXCHANGE_CODE_INVALID: "EXCHANGE_CODE_INVALID";
+    /** The render token expired at the session ceiling. Ends the session like SESSION_EXPIRED. */
     readonly RENDER_TOKEN_EXPIRED: "RENDER_TOKEN_EXPIRED";
     /** The render token failed signature, audience, or format checks. Needs a new session. */
     readonly RENDER_TOKEN_INVALID: "RENDER_TOKEN_INVALID";
-    /** Refresh rejected: the page origin is not on the session's allowlist. Terminal. */
+    /** The page origin is not on the session's allowlist. Terminal. */
     readonly ORIGIN_NOT_ALLOWED: "ORIGIN_NOT_ALLOWED";
-    /** Refresh rejected: the session was revoked (token reuse included). Terminal. */
-    readonly SESSION_REVOKED: "SESSION_REVOKED";
-    /** Refresh rejected: the session reached its expiration ceiling. Terminal. */
-    readonly SESSION_LIMIT_REACHED: "SESSION_LIMIT_REACHED";
-    /** Refresh rejected: unknown session, or one that names a component this API build lacks. Terminal. */
-    readonly SESSION_INVALID: "SESSION_INVALID";
-    /** Refresh could not mint a render token: server misconfiguration. Terminal regardless of status. */
-    readonly RENDER_TOKEN_FAILED: "RENDER_TOKEN_FAILED";
 };
 export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];

package/dist/index.js

@@ -1475,9 +1475,8 @@ const eventEnvelopeSchema = object({
     source: literal(MESSAGE_SOURCE),
     version: literal(MESSAGE_VERSION),
     type: string(),
-    instanceId: string(),
     // Deliberately unvalidated here. A malformed payload must fail at the
-    // message schema, AFTER the instance is identified, so the failure comes
+    // message schema, AFTER the sender is identified, so the failure comes
     // back as PROTOCOL_ERROR instead of being dropped as foreign traffic.
     payload: optional(unknown()),
 });
@@ -1640,7 +1639,8 @@ const baseInboundEvents = {
  */
 const outboundMessages = {
     CONFIG_SET: object({
-        sessionToken: string(),
+        /** Single-use code the frame redeems at Payhub for its session cookie. */
+        exchangeCode: string(),
         options: optional(record),
         appearance: optional(appearanceSchema),
     }),
@@ -1648,10 +1648,6 @@ const outboundMessages = {
     FOCUS_REQUEST: object({ field: optional(string()) }),
     BLUR_REQUEST: emptyPayload,
     SUBMIT_REQUEST: emptyPayload,
-    SESSION_UPDATE: object({
-        sessionToken: string(),
-        replace: optional(boolean()),
-    }),
     DESTROY: emptyPayload,
     PROTOCOL_ERROR: object({ originalType: string(), reason: string() }),
 };
@@ -1809,6 +1805,7 @@ const payInDescriptor = register({
     type: 'payin',
     displayName: 'PayIn',
     embedPath: '/embed/payin',
+    endsOnSuccess: true,
     optionsSchema: payinOptionsSchema,
     eventSchemas: payInEventSchemas,
 });
@@ -1823,27 +1820,24 @@ const ErrorCodes = {
     OUTCOME_UNKNOWN: 'OUTCOME_UNKNOWN',
     /** This session already completed an operation. Create a new session. */
     SESSION_COMPLETED: 'SESSION_COMPLETED',
+    /** The session reached its expiration ceiling. Create a new session and mount again. */
     SESSION_EXPIRED: 'SESSION_EXPIRED',
-    SESSION_REFRESH_FAILED: 'SESSION_REFRESH_FAILED',
-    /** Reported by an iframe whose call was rejected for an expired JWT. Triggers a refresh. */
-    TOKEN_EXPIRED: 'TOKEN_EXPIRED',
-    /**
-     * Reported by an iframe whose render token no longer renders. The SDK recreates the frame
-     * with the latest render token.
-     */
+    /** The session was revoked. Terminal. */
+    SESSION_REVOKED: 'SESSION_REVOKED',
+    /** The session reached its expiration ceiling on the server. Terminal. */
+    SESSION_LIMIT_REACHED: 'SESSION_LIMIT_REACHED',
+    /** Unknown session, or one that names a component this API build lacks. Terminal. */
+    SESSION_INVALID: 'SESSION_INVALID',
+    /** The browser did not send the session cookie back to the frame. Terminal. */
+    SESSION_COOKIE_UNAVAILABLE: 'SESSION_COOKIE_UNAVAILABLE',
+    /** The exchange code is unknown, expired, already used, or issued for another key. */
+    EXCHANGE_CODE_INVALID: 'EXCHANGE_CODE_INVALID',
+    /** The render token expired at the session ceiling. Ends the session like SESSION_EXPIRED. */
     RENDER_TOKEN_EXPIRED: 'RENDER_TOKEN_EXPIRED',
     /** The render token failed signature, audience, or format checks. Needs a new session. */
     RENDER_TOKEN_INVALID: 'RENDER_TOKEN_INVALID',
-    /** Refresh rejected: the page origin is not on the session's allowlist. Terminal. */
+    /** The page origin is not on the session's allowlist. Terminal. */
     ORIGIN_NOT_ALLOWED: 'ORIGIN_NOT_ALLOWED',
-    /** Refresh rejected: the session was revoked (token reuse included). Terminal. */
-    SESSION_REVOKED: 'SESSION_REVOKED',
-    /** Refresh rejected: the session reached its expiration ceiling. Terminal. */
-    SESSION_LIMIT_REACHED: 'SESSION_LIMIT_REACHED',
-    /** Refresh rejected: unknown session, or one that names a component this API build lacks. Terminal. */
-    SESSION_INVALID: 'SESSION_INVALID',
-    /** Refresh could not mint a render token: server misconfiguration. Terminal regardless of status. */
-    RENDER_TOKEN_FAILED: 'RENDER_TOKEN_FAILED',
 };
 
 const BASE_COMPONENT_EVENT_NAMES = [

package/dist/payin/schema.d.ts

@@ -92,13 +92,41 @@ export declare const payinEvents: {
         vendorId: z.ZodMiniString<string>;
     }, z.core.$strip>;
 };
+/** The session operation the payload reports on. */
+export type PayInOperation = 'pay' | 'auth' | 'tokenize';
 /**
- * SUBMIT_RESULT.data for PayIn. Open on purpose: the transaction result grows
- * fields the SDK does not interpret, and it forwards all of them.
+ * SUBMIT_RESULT.data for PayIn: the `success` event payload and the `submit()`
+ * result. One closed shape for every operation, so a partner handles the
+ * result without branching on the operation. payhub builds it from the API
+ * result; the API body itself never reaches the page.
  */
 export type PayInSuccessPayload = {
-    /** The transaction ID for pay or auth sessions. */
+    operation: PayInOperation;
+    /** The method the buyer used. */
+    method: PaymentMethodName;
+    /** The Payabli transaction id. Present for `pay` and `auth`. */
     transactionId?: string;
-    /** The saved payment method ID for tokenize sessions. */
-    referenceId?: string;
-} & Record<string, unknown>;
+    /**
+     * The saved payment method id. Present for `tokenize`, and for `pay` or `auth`
+     * when the session saved the method. Pass it back as `storedMethodId` on a
+     * later payment.
+     */
+    storedMethodId?: string;
+    /** The Payabli customer id when the API created or matched a customer. */
+    customerId?: number;
+    paymentMethod?: {
+        /** The account with every digit but the last four hidden, for example `5XXXXXXXXXXX0055`. */
+        maskedAccount?: string;
+        /** The card brand (`mastercard`) or the bank account type (`checking`). */
+        accountType?: string;
+        /** The card expiration, `MM/YY`. */
+        expiration?: string;
+        holderName?: string;
+    };
+    /** The charged or authorized amount. Present for `pay` and `auth`. */
+    amount?: {
+        total: number;
+        serviceFee?: number;
+        currency?: string;
+    };
+};

package/dist/protocol/base.d.ts

@@ -97,7 +97,7 @@ export type BaseInboundType = keyof typeof baseInboundEvents;
  */
 export declare const outboundMessages: {
     readonly CONFIG_SET: z.ZodMiniObject<{
-        sessionToken: z.ZodMiniString<string>;
+        exchangeCode: z.ZodMiniString<string>;
         options: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>>;
         appearance: z.ZodMiniOptional<z.ZodMiniObject<{
             layout: z.ZodMiniOptional<z.ZodMiniEnum<{
@@ -133,10 +133,6 @@ export declare const outboundMessages: {
     }, z.core.$strip>;
     readonly BLUR_REQUEST: z.ZodMiniObject<{}, z.core.$strip>;
     readonly SUBMIT_REQUEST: z.ZodMiniObject<{}, z.core.$strip>;
-    readonly SESSION_UPDATE: z.ZodMiniObject<{
-        sessionToken: z.ZodMiniString<string>;
-        replace: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
-    }, z.core.$strip>;
     readonly DESTROY: z.ZodMiniObject<{}, z.core.$strip>;
     readonly PROTOCOL_ERROR: z.ZodMiniObject<{
         originalType: z.ZodMiniString<string>;

package/dist/protocol/envelope.d.ts

@@ -16,7 +16,6 @@ export declare const eventEnvelopeSchema: z.ZodMiniObject<{
     source: z.ZodMiniLiteral<"payabli">;
     version: z.ZodMiniLiteral<1>;
     type: z.ZodMiniString<string>;
-    instanceId: z.ZodMiniString<string>;
     payload: z.ZodMiniOptional<z.ZodMiniUnknown>;
 }, z.core.$strip>;
 export type EventEnvelope = z.infer<typeof eventEnvelopeSchema>;

package/dist/registry.d.ts

@@ -27,6 +27,8 @@ export type ComponentDescriptor<T extends ComponentType = ComponentType> = {
     type: T;
     displayName: string;
     embedPath: `/embed/${string}`;
+    /** A successful submit ends this component, so the SDK destroys it after `success`. */
+    endsOnSuccess: boolean;
     /**
      * Wire schema for CONFIG_SET.options. Payhub parses the options payload
      * with this same object, so the partner-facing options type and the

package/dist/sdk.d.ts

@@ -8,25 +8,37 @@
  */
 import type { ComponentEventKey, ComponentEventMap, ComponentOptions, ComponentType } from './registry.js';
 import type { AppearanceOptions } from './protocol/base.js';
+/**
+ * The `data` of `POST /v2/{entryName}/Session/init`, passed through from the partner server.
+ * It holds no API credential: the session JWT stays on Payabli's servers.
+ */
 export interface Session {
-    /** Session JWT returned by `POST /v2/{entryName}/Session/init`. */
-    sessionToken: string;
+    sessionId: string;
     /**
-     * Signed render token from the same response. The SDK puts it in the iframe URL as the
-     * `rt` parameter, where it identifies the entrypoint and carries the origin allowlist.
-     * It authenticates no API call. Every refresh returns a fresh one.
+     * Signed render token. The SDK puts it in the iframe URL as the `rt` parameter, where it
+     * identifies the entrypoint and carries the origin allowlist. It authenticates no API call.
      */
     renderToken: string;
-    /** Organization or paypoint slug the session belongs to. Used to build the refresh URL. */
+    /**
+     * One single-use code per component key. Each frame redeems its code once, within 60
+     * seconds of `Session/init`, for a session cookie.
+     */
+    exchangeCodes: Record<string, string>;
+    /** Organization or paypoint slug the session belongs to. */
     entryName: string;
     environment: string;
-    /** ISO 8601 expiry of `sessionToken`. The SDK refreshes at ~80% of the remaining time. */
+    /** ISO 8601 session ceiling. The SDK ends the session at this time. */
     expiresAt: string;
 }
 export interface PayabliConfig {
     session: Session;
 }
 export interface CreateOptions<T extends ComponentType = ComponentType> {
+    /**
+     * The component key from `Session/init`. Required when the session has more than one
+     * component. Defaults to the component type.
+     */
+    key?: string;
     appearance?: AppearanceOptions;
     options?: ComponentOptions<T>;
     prefill?: T extends 'payin' ? never : Record<string, string>;
@@ -70,7 +82,6 @@ export type PayabliInstance = {
     on: <K extends SessionEventKey>(event: K, handler: (payload: SessionEventMap[K]) => void, options?: {
         signal?: AbortSignal;
     }) => () => void;
-    updateSession: (session: Session) => void;
     destroy: () => void;
 };
 export type PayabliConstructor = (config: PayabliConfig) => PayabliInstance;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payabli/component-contracts",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Wire schemas, component registry, and partner-facing types shared by the Payabli embedded components SDK and payhub.",
   "private": false,
   "license": "MIT",