@notabene/javascript-sdk 2.19.1 → 2.20.0

package/package.json

@@ -10,7 +10,7 @@
   "author": "Notabene <developers@notabene.id>",
   "license": "MIT",
   "packageManager": "yarn@4.5.1",
-  "version": "2.19.1",
+  "version": "2.20.0",
   "source": "src/notabene.ts",
   "main": "dist/cjs/notabene.cjs",
   "module": "dist/esm/notabene.js",

package/src/notabene.ts

@@ -102,6 +102,7 @@ export type {
 export type { Invoice } from './types';
 export {
   ConnectionManager,
+  decryptCounterpartyAssistPayload,
   getRefreshResult,
   type ConnectionData,
   type ConnectionMetadata,

package/src/types.ts

@@ -584,6 +584,12 @@ export interface Transaction extends ComponentRequest {
 export interface RefreshSource {
   url: URI;
   key: string;
+  /**
+   * The connection id (also embedded in `url`). Exposed directly so consumers can
+   * correlate a Counterparty Assist webhook event (whose `payload.id` is this id)
+   * without parsing it out of the url.
+   */
+  id: string;
 }
 
 export interface Refreshable {
@@ -881,6 +887,17 @@ export type CounterpartyAssistConfig =
       counterpartyTypes: PersonType[];
       /** @remarks Requires a transactionId to be passed in. */
       identityVerification?: IdentityVerificationConfig;
+      /**
+       * Optional URL that receives an `EC.counterpartyAssist*` webhook when the
+       * counterparty completes or closes their part. MVP-only per-link override;
+       * superseded by Portal-managed subscriptions post-migration.
+       *
+       * Transmitted and stored as plaintext, so do not embed secrets (e.g. `?token=`)
+       * in this URL. Payloads carry the encrypted `sealed` blob (a successful decrypt
+       * is itself an authenticity check); signed delivery is provided by the future
+       * Svix-backed pipeline.
+       */
+      webhookUrl?: string;
     };
 
 /**

package/src/utils/__tests__/connections.test.ts

@@ -4,6 +4,7 @@ import type { DID, RefreshSource } from '../../types';
 import {
   ConnectionManager,
   type ConnectionStatus,
+  decryptCounterpartyAssistPayload,
   getRefreshResult,
   type TransactionType,
 } from '../connections';
@@ -53,6 +54,7 @@ const arbConnectionMetadata = fc.record({
   participants: fc.array(fc.string(), { minLength: 1 }), // At least one participant
   nodeUrl: fc.webUrl(),
   transactionType: fc.constantFrom<TransactionType>('withdraw', 'deposit'),
+  webhookUrl: fc.option(fc.webUrl(), { nil: undefined }),
 });
 
 describe('ConnectionManager', () => {
@@ -317,6 +319,7 @@ describe('ConnectionManager', () => {
     const refreshSource: RefreshSource = {
       url: 'https://test-endpoint.com',
       key: sealed.key,
+      id: 'test-id',
     };
 
     // Common metadata for all tests
@@ -385,6 +388,7 @@ describe('ConnectionManager', () => {
       const completedRefreshSource: RefreshSource = {
         url: 'https://test-endpoint.com',
         key: completedSealed.key,
+        id: 'test-id',
       };
 
       const mockResponse = createMockResponse(
@@ -435,3 +439,28 @@ describe('ConnectionManager', () => {
     });
   });
 });
+
+describe('decryptCounterpartyAssistPayload', () => {
+  it('round-trips a sealed payload back to the original object', async () => {
+    const original = { result: { ref: 'abc' }, tx: { amount: '10' } };
+    const sealed = await seal(original);
+
+    const decrypted = await decryptCounterpartyAssistPayload<typeof original>({
+      sealed: sealed.ciphertext,
+      key: sealed.key,
+    });
+
+    expect(decrypted).toEqual(original);
+  });
+
+  it('throws when the key is wrong', async () => {
+    const sealed = await seal({ a: 1 });
+    const other = await seal({ b: 2 });
+    await expect(
+      decryptCounterpartyAssistPayload({
+        sealed: sealed.ciphertext,
+        key: other.key,
+      }),
+    ).rejects.toThrow();
+  });
+});

package/src/utils/connections.ts

@@ -24,6 +24,14 @@ export interface ConnectionMetadata {
   readonly participants: readonly string[];
   readonly transactionType: TransactionType;
   readonly locale?: string;
+  /**
+   * Delivery target for Counterparty Assist completion/closure webhooks.
+   * Sent and stored as plaintext so the connection can route the event, so do not
+   * embed secrets (e.g. `?token=`) in this URL. Webhook payloads carry the encrypted
+   * `sealed` blob, whose successful decryption is itself an authenticity check;
+   * signed delivery is provided by the future Svix-backed pipeline.
+   */
+  readonly webhookUrl?: string;
 }
 
 export interface ConnectionResponse<T extends ComponentRequest> {
@@ -61,7 +69,7 @@ export type ConnectionResult<T extends ComponentRequest> =
  * @returns Promise resolving to connection result with decrypted data
  */
 export async function getRefreshResult<T extends ComponentRequest>(
-  refreshSource: RefreshSource,
+  refreshSource: Pick<RefreshSource, 'url' | 'key'>,
 ): Promise<ConnectionResult<T>> {
   const response = await fetch(refreshSource.url, {
     method: 'GET',
@@ -109,6 +117,22 @@ export async function getRefreshResult<T extends ComponentRequest>(
   };
 }
 
+/**
+ * Decrypt a Counterparty Assist webhook payload with the key the VASP captured
+ * at connection creation. Single call, no network fetch (the webhook already
+ * carried the ciphertext).
+ * @public
+ */
+export async function decryptCounterpartyAssistPayload<T>({
+  sealed,
+  key,
+}: {
+  sealed: string;
+  key: string;
+}): Promise<T> {
+  return unseal<T>({ ciphertext: sealed, key });
+}
+
 /**
  * Manages encrypted connections using Cloudflare Durable Objects
  */