@contractspec/example.openbanking-powens 3.7.6 → 3.7.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/example.openbanking-powens",
-  "version": "3.7.6",
+  "version": "3.7.10",
   "description": "OpenBanking Powens example: OAuth callback + webhook handler patterns (provider + workflows).",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -41,6 +41,18 @@
       "node": "./dist/node/handlers/webhook-handler.js",
       "default": "./dist/handlers/webhook-handler.js"
     },
+    "./jobs": {
+      "types": "./dist/jobs/index.d.ts",
+      "bun": "./dist/jobs/index.js",
+      "node": "./dist/node/jobs/index.js",
+      "default": "./dist/jobs/index.js"
+    },
+    "./jobs/powens-sync-dispatch.job": {
+      "types": "./dist/jobs/powens-sync-dispatch.job.d.ts",
+      "bun": "./dist/jobs/powens-sync-dispatch.job.js",
+      "node": "./dist/node/jobs/powens-sync-dispatch.job.js",
+      "default": "./dist/jobs/powens-sync-dispatch.job.js"
+    },
     "./openbanking-powens.feature": {
       "types": "./dist/openbanking-powens.feature.d.ts",
       "bun": "./dist/openbanking-powens.feature.js",
@@ -57,20 +69,20 @@
     "dev": "contractspec-bun-build dev",
     "clean": "rimraf dist .turbo",
     "lint": "bun lint:fix",
-    "lint:fix": "eslint src --fix",
-    "lint:check": "eslint src",
+    "lint:fix": "biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .",
+    "lint:check": "biome check .",
     "test": "bun test --pass-with-no-tests",
     "prebuild": "contractspec-bun-build prebuild",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/integration.providers-impls": "3.7.6",
-    "@contractspec/lib.contracts-spec": "3.7.6"
+    "@contractspec/integration.providers-impls": "3.8.2",
+    "@contractspec/lib.contracts-spec": "4.1.2"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.6",
+    "@contractspec/tool.typescript": "3.7.8",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.7.6"
+    "@contractspec/tool.bun": "3.7.8"
   },
   "publishConfig": {
     "access": "public",
@@ -111,6 +123,18 @@
         "node": "./dist/node/handlers/webhook-handler.js",
         "default": "./dist/handlers/webhook-handler.js"
       },
+      "./jobs": {
+        "types": "./dist/jobs/index.d.ts",
+        "bun": "./dist/jobs/index.js",
+        "node": "./dist/node/jobs/index.js",
+        "default": "./dist/jobs/index.js"
+      },
+      "./jobs/powens-sync-dispatch.job": {
+        "types": "./dist/jobs/powens-sync-dispatch.job.d.ts",
+        "bun": "./dist/jobs/powens-sync-dispatch.job.js",
+        "node": "./dist/node/jobs/powens-sync-dispatch.job.js",
+        "default": "./dist/jobs/powens-sync-dispatch.job.js"
+      },
       "./openbanking-powens.feature": {
         "types": "./dist/openbanking-powens.feature.d.ts",
         "bun": "./dist/openbanking-powens.feature.js",

package/src/contracts.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from 'bun:test';
+import { OpenbankingPowensFeature, PowensSyncDispatchJob } from './index';
+
+describe('@contractspec/example.openbanking-powens', () => {
+	test('exports the canonical job spec', () => {
+		expect(PowensSyncDispatchJob.meta.key).toBe(
+			'openbanking-powens.job.sync-dispatch'
+		);
+		expect(PowensSyncDispatchJob.timeoutMs).toBe(60_000);
+		expect(OpenbankingPowensFeature.meta.key).toBe('openbanking-powens');
+	});
+});

package/src/docs/openbanking-powens.docblock.ts

@@ -2,27 +2,27 @@ import type { DocBlock } from '@contractspec/lib.contracts-spec/docs';
 import { registerDocBlocks } from '@contractspec/lib.contracts-spec/docs';
 
 const blocks: DocBlock[] = [
-  {
-    id: 'docs.examples.openbanking-powens',
-    title: 'Open Banking — Powens (example)',
-    summary:
-      'Framework-neutral OAuth callback + webhook handler patterns for Powens, orchestrating canonical sync workflows.',
-    kind: 'reference',
-    visibility: 'public',
-    route: '/docs/examples/openbanking-powens',
-    tags: ['openbanking', 'powens', 'integration', 'example'],
-    body: `## What this example shows\n- OAuth callback handler: exchange auth code, map powens user, enqueue sync workflow.\n- Webhook handler: verify signature, route event → workflow, optionally refresh balances.\n\n## Guardrails\n- Secrets via secret providers/env only.\n- Verify webhook signatures.\n- Keep side effects explicit: enqueue workflows instead of mutating canonical stores inline.`,
-  },
-  {
-    id: 'docs.examples.openbanking-powens.usage',
-    title: 'Open Banking — Powens — Usage',
-    summary: 'How to integrate the handlers in a fetch-compatible runtime.',
-    kind: 'usage',
-    visibility: 'public',
-    route: '/docs/examples/openbanking-powens/usage',
-    tags: ['openbanking', 'usage'],
-    body: `## Usage\n- Wire \`powensOAuthCallbackHandler(req)\` at your OAuth redirect route.\n- Wire \`powensWebhookHandler(req)\` at your webhook route.\n\n## Notes\n- Replace the fake stores with your app-layer persistence.\n- Enqueue ContractSpec workflows for canonical upserts and telemetry.`,
-  },
+	{
+		id: 'docs.examples.openbanking-powens',
+		title: 'Open Banking — Powens (example)',
+		summary:
+			'Framework-neutral OAuth callback + webhook handler patterns for Powens, orchestrating canonical sync workflows.',
+		kind: 'reference',
+		visibility: 'public',
+		route: '/docs/examples/openbanking-powens',
+		tags: ['openbanking', 'powens', 'integration', 'example'],
+		body: `## What this example shows\n- OAuth callback handler: exchange auth code, map powens user, enqueue sync workflow.\n- Webhook handler: verify signature, route event → workflow, optionally refresh balances.\n\n## Guardrails\n- Secrets via secret providers/env only.\n- Verify webhook signatures.\n- Keep side effects explicit: enqueue workflows instead of mutating canonical stores inline.`,
+	},
+	{
+		id: 'docs.examples.openbanking-powens.usage',
+		title: 'Open Banking — Powens — Usage',
+		summary: 'How to integrate the handlers in a fetch-compatible runtime.',
+		kind: 'usage',
+		visibility: 'public',
+		route: '/docs/examples/openbanking-powens/usage',
+		tags: ['openbanking', 'usage'],
+		body: `## Usage\n- Wire \`powensOAuthCallbackHandler(req)\` at your OAuth redirect route.\n- Wire \`powensWebhookHandler(req)\` at your webhook route.\n\n## Notes\n- Replace the fake stores with your app-layer persistence.\n- Enqueue ContractSpec workflows for canonical upserts and telemetry.`,
+	},
 ];
 
 registerDocBlocks(blocks);

package/src/example.ts

@@ -1,32 +1,32 @@
 import { defineExample } from '@contractspec/lib.contracts-spec';
 
 const example = defineExample({
-  meta: {
-    key: 'openbanking-powens',
-    version: '1.0.0',
-    title: 'Open Banking — Powens',
-    description:
-      'OAuth callback + webhook handler patterns for Powens open banking integration (provider + workflow orchestration).',
-    kind: 'integration',
-    visibility: 'public',
-    stability: 'experimental',
-    owners: ['@platform.core'],
-    tags: ['openbanking', 'powens', 'oauth', 'webhooks', 'integrations'],
-  },
-  docs: {
-    rootDocId: 'docs.examples.openbanking-powens',
-    usageDocId: 'docs.examples.openbanking-powens.usage',
-  },
-  entrypoints: {
-    packageName: '@contractspec/example.openbanking-powens',
-    docs: './docs',
-  },
-  surfaces: {
-    templates: true,
-    sandbox: { enabled: true, modes: ['markdown', 'specs'] },
-    studio: { enabled: true, installable: true },
-    mcp: { enabled: true },
-  },
+	meta: {
+		key: 'openbanking-powens',
+		version: '1.0.0',
+		title: 'Open Banking — Powens',
+		description:
+			'OAuth callback + webhook handler patterns for Powens open banking integration (provider + workflow orchestration).',
+		kind: 'integration',
+		visibility: 'public',
+		stability: 'experimental',
+		owners: ['@platform.core'],
+		tags: ['openbanking', 'powens', 'oauth', 'webhooks', 'integrations'],
+	},
+	docs: {
+		rootDocId: 'docs.examples.openbanking-powens',
+		usageDocId: 'docs.examples.openbanking-powens.usage',
+	},
+	entrypoints: {
+		packageName: '@contractspec/example.openbanking-powens',
+		docs: './docs',
+	},
+	surfaces: {
+		templates: true,
+		sandbox: { enabled: true, modes: ['markdown', 'specs'] },
+		studio: { enabled: true, installable: true },
+		mcp: { enabled: true },
+	},
 });
 
 export default example;

package/src/handlers/oauth-callback.ts

@@ -4,110 +4,111 @@
  * This example stays framework-neutral: it operates on the standard `Request`
  * type so it can be used in Next.js, Elysia, or any fetch-compatible runtime.
  */
-import { PowensOpenBankingProvider } from '@contractspec/integration.providers-impls/impls/powens-openbanking';
+
 import type { PowensEnvironment } from '@contractspec/integration.providers-impls/impls/powens-client';
+import { PowensOpenBankingProvider } from '@contractspec/integration.providers-impls/impls/powens-openbanking';
 
 export async function powensOAuthCallbackHandler(req: Request) {
-  const url = new URL(req.url);
-  const code = url.searchParams.get('code');
-  const state = url.searchParams.get('state');
-  const userUuid = url.searchParams.get('user_uuid');
-
-  if (!code || !state || !userUuid) {
-    return new Response('Missing Powens OAuth params', { status: 400 });
-  }
-
-  const connection = await getConnectionByState(state);
-  if (!connection) {
-    return new Response('Unknown Powens OAuth state', { status: 404 });
-  }
-
-  const secrets = await getPowensSecretsForConnection(connection.meta.id);
-
-  const provider = new PowensOpenBankingProvider({
-    clientId: secrets.clientId,
-    clientSecret: secrets.clientSecret,
-    apiKey: secrets.apiKey,
-    environment: connection.config.environment as PowensEnvironment,
-    baseUrl: connection.config.baseUrl as string | undefined,
-  });
-
-  const preview = await provider.listAccounts({
-    tenantId: connection.meta.tenantId,
-    connectionId: connection.meta.id,
-    userId: userUuid,
-  });
-
-  await connection.storePowensUser({
-    tenantUserId: connection.meta.tenantUserId,
-    powensUserUuid: userUuid,
-    authCode: code,
-  });
-
-  await enqueueWorkflow('pfo.workflow.sync-openbanking-accounts', {
-    tenantId: connection.meta.tenantId,
-    userUuid,
-    connectionId: connection.meta.id,
-    previewAccounts: preview.accounts,
-  });
-
-  const redirectBase = process.env.APP_DASHBOARD_URL ?? '';
-  return Response.redirect(
-    `${redirectBase}/banking/linked?tenant=${connection.meta.tenantId}`,
-    302
-  );
+	const url = new URL(req.url);
+	const code = url.searchParams.get('code');
+	const state = url.searchParams.get('state');
+	const userUuid = url.searchParams.get('user_uuid');
+
+	if (!code || !state || !userUuid) {
+		return new Response('Missing Powens OAuth params', { status: 400 });
+	}
+
+	const connection = await getConnectionByState(state);
+	if (!connection) {
+		return new Response('Unknown Powens OAuth state', { status: 404 });
+	}
+
+	const secrets = await getPowensSecretsForConnection(connection.meta.id);
+
+	const provider = new PowensOpenBankingProvider({
+		clientId: secrets.clientId,
+		clientSecret: secrets.clientSecret,
+		apiKey: secrets.apiKey,
+		environment: connection.config.environment as PowensEnvironment,
+		baseUrl: connection.config.baseUrl as string | undefined,
+	});
+
+	const preview = await provider.listAccounts({
+		tenantId: connection.meta.tenantId,
+		connectionId: connection.meta.id,
+		userId: userUuid,
+	});
+
+	await connection.storePowensUser({
+		tenantUserId: connection.meta.tenantUserId,
+		powensUserUuid: userUuid,
+		authCode: code,
+	});
+
+	await enqueueWorkflow('pfo.workflow.sync-openbanking-accounts', {
+		tenantId: connection.meta.tenantId,
+		userUuid,
+		connectionId: connection.meta.id,
+		previewAccounts: preview.accounts,
+	});
+
+	const redirectBase = process.env.APP_DASHBOARD_URL ?? '';
+	return Response.redirect(
+		`${redirectBase}/banking/linked?tenant=${connection.meta.tenantId}`,
+		302
+	);
 }
 
 interface ExamplePowensSecrets {
-  clientId: string;
-  clientSecret: string;
-  apiKey?: string;
+	clientId: string;
+	clientSecret: string;
+	apiKey?: string;
 }
 
 interface ExampleIntegrationConnection {
-  meta: {
-    id: string;
-    tenantId: string;
-    tenantUserId: string;
-  };
-  config: {
-    environment: PowensEnvironment;
-    baseUrl?: string;
-  };
-  storePowensUser(input: {
-    tenantUserId: string;
-    powensUserUuid: string;
-    authCode: string;
-  }): Promise<void>;
+	meta: {
+		id: string;
+		tenantId: string;
+		tenantUserId: string;
+	};
+	config: {
+		environment: PowensEnvironment;
+		baseUrl?: string;
+	};
+	storePowensUser(input: {
+		tenantUserId: string;
+		powensUserUuid: string;
+		authCode: string;
+	}): Promise<void>;
 }
 
 async function getConnectionByState(
-  state: string
+	state: string
 ): Promise<ExampleIntegrationConnection | null> {
-  const record = fakeDatabase.connections.find((conn) => conn.state === state);
-  return record ?? null;
+	const record = fakeDatabase.connections.find((conn) => conn.state === state);
+	return record ?? null;
 }
 
 async function getPowensSecretsForConnection(
-  connectionId: string
+	connectionId: string
 ): Promise<ExamplePowensSecrets> {
-  const secret = fakeSecretStore[connectionId];
-  if (!secret) throw new Error(`Missing Powens secrets for ${connectionId}`);
-  return secret;
+	const secret = fakeSecretStore[connectionId];
+	if (!secret) throw new Error(`Missing Powens secrets for ${connectionId}`);
+	return secret;
 }
 
 async function enqueueWorkflow(name: string, input: Record<string, unknown>) {
-  await fakeWorkflowQueue.enqueue({ name, input });
+	await fakeWorkflowQueue.enqueue({ name, input });
 }
 
 const fakeDatabase = {
-  connections: [] as (ExampleIntegrationConnection & { state: string })[],
+	connections: [] as (ExampleIntegrationConnection & { state: string })[],
 };
 
 const fakeSecretStore: Record<string, ExamplePowensSecrets> = {};
 
 const fakeWorkflowQueue = {
-  enqueue: async (_payload: Record<string, unknown>) => {
-    /* no-op */
-  },
+	enqueue: async (_payload: Record<string, unknown>) => {
+		/* no-op */
+	},
 };

package/src/handlers/webhook-handler.ts

@@ -4,144 +4,145 @@
  * Verifies signature, then enqueues the canonical workflows to keep the ledger
  * in sync. Unknown events are ignored (or can be recorded by the app layer).
  */
-import { createHmac, timingSafeEqual } from 'crypto';
-import { PowensOpenBankingProvider } from '@contractspec/integration.providers-impls/impls/powens-openbanking';
+
 import type { PowensEnvironment } from '@contractspec/integration.providers-impls/impls/powens-client';
+import { PowensOpenBankingProvider } from '@contractspec/integration.providers-impls/impls/powens-openbanking';
+import { createHmac, timingSafeEqual } from 'crypto';
 
 export async function powensWebhookHandler(req: Request) {
-  const signature = req.headers.get('x-powens-signature');
-  const stateHeader = req.headers.get('x-powens-state');
-  const payload = await req.text();
-
-  if (!signature || !stateHeader) {
-    return new Response('Missing Powens signature headers', { status: 400 });
-  }
-
-  const connection = await getConnectionByState(stateHeader);
-  if (!connection) {
-    return new Response('Unknown Powens state header', { status: 404 });
-  }
-
-  const secrets = await getPowensSecretsForConnection(connection.meta.id);
-  if (!verifySignature(payload, signature, secrets.webhookSecret)) {
-    return new Response('Invalid Powens webhook signature', { status: 401 });
-  }
-
-  const event = JSON.parse(payload) as PowensWebhookEvent;
-  const provider = new PowensOpenBankingProvider({
-    clientId: secrets.clientId,
-    clientSecret: secrets.clientSecret,
-    apiKey: secrets.apiKey,
-    environment: connection.config.environment as PowensEnvironment,
-    baseUrl: connection.config.baseUrl as string | undefined,
-  });
-
-  switch (event.type) {
-    case 'connection.updated':
-    case 'user.sync.completed': {
-      await enqueueWorkflow('pfo.workflow.sync-openbanking-accounts', {
-        tenantId: connection.meta.tenantId,
-        connectionId: connection.meta.id,
-        userUuid: event.user_uuid,
-      });
-      break;
-    }
-    case 'transactions.created':
-    case 'transactions.updated': {
-      await enqueueWorkflow('pfo.workflow.sync-openbanking-transactions', {
-        tenantId: connection.meta.tenantId,
-        connectionId: connection.meta.id,
-        userUuid: event.user_uuid,
-        accountId: event.account_uuid,
-      });
-      break;
-    }
-    default:
-      await logUnmappedEvent(event);
-  }
-
-  if (event.account_uuid) {
-    await provider.getBalances({
-      tenantId: connection.meta.tenantId,
-      connectionId: connection.meta.id,
-      accountId: event.account_uuid,
-    });
-  }
-
-  return new Response('OK', { status: 200 });
+	const signature = req.headers.get('x-powens-signature');
+	const stateHeader = req.headers.get('x-powens-state');
+	const payload = await req.text();
+
+	if (!signature || !stateHeader) {
+		return new Response('Missing Powens signature headers', { status: 400 });
+	}
+
+	const connection = await getConnectionByState(stateHeader);
+	if (!connection) {
+		return new Response('Unknown Powens state header', { status: 404 });
+	}
+
+	const secrets = await getPowensSecretsForConnection(connection.meta.id);
+	if (!verifySignature(payload, signature, secrets.webhookSecret)) {
+		return new Response('Invalid Powens webhook signature', { status: 401 });
+	}
+
+	const event = JSON.parse(payload) as PowensWebhookEvent;
+	const provider = new PowensOpenBankingProvider({
+		clientId: secrets.clientId,
+		clientSecret: secrets.clientSecret,
+		apiKey: secrets.apiKey,
+		environment: connection.config.environment as PowensEnvironment,
+		baseUrl: connection.config.baseUrl as string | undefined,
+	});
+
+	switch (event.type) {
+		case 'connection.updated':
+		case 'user.sync.completed': {
+			await enqueueWorkflow('pfo.workflow.sync-openbanking-accounts', {
+				tenantId: connection.meta.tenantId,
+				connectionId: connection.meta.id,
+				userUuid: event.user_uuid,
+			});
+			break;
+		}
+		case 'transactions.created':
+		case 'transactions.updated': {
+			await enqueueWorkflow('pfo.workflow.sync-openbanking-transactions', {
+				tenantId: connection.meta.tenantId,
+				connectionId: connection.meta.id,
+				userUuid: event.user_uuid,
+				accountId: event.account_uuid,
+			});
+			break;
+		}
+		default:
+			await logUnmappedEvent(event);
+	}
+
+	if (event.account_uuid) {
+		await provider.getBalances({
+			tenantId: connection.meta.tenantId,
+			connectionId: connection.meta.id,
+			accountId: event.account_uuid,
+		});
+	}
+
+	return new Response('OK', { status: 200 });
 }
 
 interface PowensWebhookEvent {
-  type: string;
-  user_uuid: string;
-  connection_uuid: string;
-  account_uuid?: string;
+	type: string;
+	user_uuid: string;
+	connection_uuid: string;
+	account_uuid?: string;
 }
 
 interface ExamplePowensSecrets {
-  clientId: string;
-  clientSecret: string;
-  apiKey?: string;
-  webhookSecret: string;
+	clientId: string;
+	clientSecret: string;
+	apiKey?: string;
+	webhookSecret: string;
 }
 
 interface ExampleIntegrationConnection {
-  meta: {
-    id: string;
-    tenantId: string;
-  };
-  config: {
-    environment: PowensEnvironment;
-    baseUrl?: string;
-  };
+	meta: {
+		id: string;
+		tenantId: string;
+	};
+	config: {
+		environment: PowensEnvironment;
+		baseUrl?: string;
+	};
 }
 
 function verifySignature(payload: string, signature: string, secret: string) {
-  const digest = createHmac('sha256', secret).update(payload).digest('hex');
-  const a = Buffer.from(digest, 'hex');
-  const b = Buffer.from(signature, 'hex');
-  return a.length === b.length && timingSafeEqual(a, b);
+	const digest = createHmac('sha256', secret).update(payload).digest('hex');
+	const a = Buffer.from(digest, 'hex');
+	const b = Buffer.from(signature, 'hex');
+	return a.length === b.length && timingSafeEqual(a, b);
 }
 
 async function getConnectionByState(
-  state: string
+	state: string
 ): Promise<ExampleIntegrationConnection | null> {
-  return fakeDatabase.connections.find((conn) => conn.state === state) ?? null;
+	return fakeDatabase.connections.find((conn) => conn.state === state) ?? null;
 }
 
 async function getPowensSecretsForConnection(
-  connectionId: string
+	connectionId: string
 ): Promise<ExamplePowensSecrets> {
-  const secret = fakeSecretStore[connectionId];
-  if (!secret) throw new Error(`Missing Powens secrets for ${connectionId}`);
-  return secret;
+	const secret = fakeSecretStore[connectionId];
+	if (!secret) throw new Error(`Missing Powens secrets for ${connectionId}`);
+	return secret;
 }
 
 async function enqueueWorkflow(name: string, input: Record<string, unknown>) {
-  await fakeWorkflowQueue.enqueue({ name, input });
+	await fakeWorkflowQueue.enqueue({ name, input });
 }
 
 async function logUnmappedEvent(_event: PowensWebhookEvent) {
-  await fakeTelemetryLogger.record({
-    event: 'openbanking.webhook.unmapped',
-    payload: 'redacted',
-  });
+	await fakeTelemetryLogger.record({
+		event: 'openbanking.webhook.unmapped',
+		payload: 'redacted',
+	});
 }
 
 const fakeDatabase = {
-  connections: [] as (ExampleIntegrationConnection & { state: string })[],
+	connections: [] as (ExampleIntegrationConnection & { state: string })[],
 };
 
 const fakeSecretStore: Record<string, ExamplePowensSecrets> = {};
 
 const fakeWorkflowQueue = {
-  enqueue: async (_payload: Record<string, unknown>) => {
-    /* no-op */
-  },
+	enqueue: async (_payload: Record<string, unknown>) => {
+		/* no-op */
+	},
 };
 
 const fakeTelemetryLogger = {
-  record: async (_payload: Record<string, unknown>) => {
-    /* no-op */
-  },
+	record: async (_payload: Record<string, unknown>) => {
+		/* no-op */
+	},
 };

package/src/index.ts

@@ -1,5 +1,6 @@
+export { default as example } from './example';
 export * from './handlers/oauth-callback';
 export * from './handlers/webhook-handler';
+export * from './jobs';
 export * from './openbanking-powens.feature';
-export { default as example } from './example';
 import './docs';

package/src/jobs/index.ts

@@ -0,0 +1 @@
+export * from './powens-sync-dispatch.job';