@contractspec/example.openbanking-powens 0.0.0-canary-20260113170453

package/dist/handlers/webhook-handler.js

@@ -0,0 +1,88 @@
+import { PowensOpenBankingProvider } from "@contractspec/integration.providers-impls/impls/powens-openbanking";
+import { createHmac, timingSafeEqual } from "crypto";
+
+//#region src/handlers/webhook-handler.ts
+/**
+* Example Powens webhook handler (fetch-compatible).
+*
+* 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).
+*/
+async function powensWebhookHandler(req) {
+	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);
+	const provider = new PowensOpenBankingProvider({
+		clientId: secrets.clientId,
+		clientSecret: secrets.clientSecret,
+		apiKey: secrets.apiKey,
+		environment: connection.config.environment,
+		baseUrl: connection.config.baseUrl
+	});
+	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 });
+}
+function verifySignature(payload, signature, secret) {
+	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) {
+	return fakeDatabase.connections.find((conn) => conn.state === state) ?? null;
+}
+async function getPowensSecretsForConnection(connectionId) {
+	const secret = fakeSecretStore[connectionId];
+	if (!secret) throw new Error(`Missing Powens secrets for ${connectionId}`);
+	return secret;
+}
+async function enqueueWorkflow(name, input) {
+	await fakeWorkflowQueue.enqueue({
+		name,
+		input
+	});
+}
+async function logUnmappedEvent(_event) {
+	await fakeTelemetryLogger.record({
+		event: "openbanking.webhook.unmapped",
+		payload: "redacted"
+	});
+}
+const fakeDatabase = { connections: [] };
+const fakeSecretStore = {};
+const fakeWorkflowQueue = { enqueue: async (_payload) => {} };
+const fakeTelemetryLogger = { record: async (_payload) => {} };
+
+//#endregion
+export { powensWebhookHandler };
+//# sourceMappingURL=webhook-handler.js.map

package/dist/handlers/webhook-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-handler.js","names":[],"sources":["../../src/handlers/webhook-handler.ts"],"sourcesContent":["/**\n * Example Powens webhook handler (fetch-compatible).\n *\n * Verifies signature, then enqueues the canonical workflows to keep the ledger\n * in sync. Unknown events are ignored (or can be recorded by the app layer).\n */\nimport { createHmac, timingSafeEqual } from 'crypto';\nimport { PowensOpenBankingProvider } from '@contractspec/integration.providers-impls/impls/powens-openbanking';\nimport type { PowensEnvironment } from '@contractspec/integration.providers-impls/impls/powens-client';\n\nexport async function powensWebhookHandler(req: Request) {\n  const signature = req.headers.get('x-powens-signature');\n  const stateHeader = req.headers.get('x-powens-state');\n  const payload = await req.text();\n\n  if (!signature || !stateHeader) {\n    return new Response('Missing Powens signature headers', { status: 400 });\n  }\n\n  const connection = await getConnectionByState(stateHeader);\n  if (!connection) {\n    return new Response('Unknown Powens state header', { status: 404 });\n  }\n\n  const secrets = await getPowensSecretsForConnection(connection.meta.id);\n  if (!verifySignature(payload, signature, secrets.webhookSecret)) {\n    return new Response('Invalid Powens webhook signature', { status: 401 });\n  }\n\n  const event = JSON.parse(payload) as PowensWebhookEvent;\n  const provider = new PowensOpenBankingProvider({\n    clientId: secrets.clientId,\n    clientSecret: secrets.clientSecret,\n    apiKey: secrets.apiKey,\n    environment: connection.config.environment as PowensEnvironment,\n    baseUrl: connection.config.baseUrl as string | undefined,\n  });\n\n  switch (event.type) {\n    case 'connection.updated':\n    case 'user.sync.completed': {\n      await enqueueWorkflow('pfo.workflow.sync-openbanking-accounts', {\n        tenantId: connection.meta.tenantId,\n        connectionId: connection.meta.id,\n        userUuid: event.user_uuid,\n      });\n      break;\n    }\n    case 'transactions.created':\n    case 'transactions.updated': {\n      await enqueueWorkflow('pfo.workflow.sync-openbanking-transactions', {\n        tenantId: connection.meta.tenantId,\n        connectionId: connection.meta.id,\n        userUuid: event.user_uuid,\n        accountId: event.account_uuid,\n      });\n      break;\n    }\n    default:\n      await logUnmappedEvent(event);\n  }\n\n  if (event.account_uuid) {\n    await provider.getBalances({\n      tenantId: connection.meta.tenantId,\n      connectionId: connection.meta.id,\n      accountId: event.account_uuid,\n    });\n  }\n\n  return new Response('OK', { status: 200 });\n}\n\ninterface PowensWebhookEvent {\n  type: string;\n  user_uuid: string;\n  connection_uuid: string;\n  account_uuid?: string;\n}\n\ninterface ExamplePowensSecrets {\n  clientId: string;\n  clientSecret: string;\n  apiKey?: string;\n  webhookSecret: string;\n}\n\ninterface ExampleIntegrationConnection {\n  meta: {\n    id: string;\n    tenantId: string;\n  };\n  config: {\n    environment: PowensEnvironment;\n    baseUrl?: string;\n  };\n}\n\nfunction verifySignature(payload: string, signature: string, secret: string) {\n  const digest = createHmac('sha256', secret).update(payload).digest('hex');\n  const a = Buffer.from(digest, 'hex');\n  const b = Buffer.from(signature, 'hex');\n  return a.length === b.length && timingSafeEqual(a, b);\n}\n\nasync function getConnectionByState(\n  state: string\n): Promise<ExampleIntegrationConnection | null> {\n  return fakeDatabase.connections.find((conn) => conn.state === state) ?? null;\n}\n\nasync function getPowensSecretsForConnection(\n  connectionId: string\n): Promise<ExamplePowensSecrets> {\n  const secret = fakeSecretStore[connectionId];\n  if (!secret) throw new Error(`Missing Powens secrets for ${connectionId}`);\n  return secret;\n}\n\nasync function enqueueWorkflow(name: string, input: Record<string, unknown>) {\n  await fakeWorkflowQueue.enqueue({ name, input });\n}\n\nasync function logUnmappedEvent(_event: PowensWebhookEvent) {\n  await fakeTelemetryLogger.record({\n    event: 'openbanking.webhook.unmapped',\n    payload: 'redacted',\n  });\n}\n\nconst fakeDatabase = {\n  connections: [] as (ExampleIntegrationConnection & { state: string })[],\n};\n\nconst fakeSecretStore: Record<string, ExamplePowensSecrets> = {};\n\nconst fakeWorkflowQueue = {\n  enqueue: async (_payload: Record<string, unknown>) => {\n    /* no-op */\n  },\n};\n\nconst fakeTelemetryLogger = {\n  record: async (_payload: Record<string, unknown>) => {\n    /* no-op */\n  },\n};\n"],"mappings":";;;;;;;;;;AAUA,eAAsB,qBAAqB,KAAc;CACvD,MAAM,YAAY,IAAI,QAAQ,IAAI,qBAAqB;CACvD,MAAM,cAAc,IAAI,QAAQ,IAAI,iBAAiB;CACrD,MAAM,UAAU,MAAM,IAAI,MAAM;AAEhC,KAAI,CAAC,aAAa,CAAC,YACjB,QAAO,IAAI,SAAS,oCAAoC,EAAE,QAAQ,KAAK,CAAC;CAG1E,MAAM,aAAa,MAAM,qBAAqB,YAAY;AAC1D,KAAI,CAAC,WACH,QAAO,IAAI,SAAS,+BAA+B,EAAE,QAAQ,KAAK,CAAC;CAGrE,MAAM,UAAU,MAAM,8BAA8B,WAAW,KAAK,GAAG;AACvE,KAAI,CAAC,gBAAgB,SAAS,WAAW,QAAQ,cAAc,CAC7D,QAAO,IAAI,SAAS,oCAAoC,EAAE,QAAQ,KAAK,CAAC;CAG1E,MAAM,QAAQ,KAAK,MAAM,QAAQ;CACjC,MAAM,WAAW,IAAI,0BAA0B;EAC7C,UAAU,QAAQ;EAClB,cAAc,QAAQ;EACtB,QAAQ,QAAQ;EAChB,aAAa,WAAW,OAAO;EAC/B,SAAS,WAAW,OAAO;EAC5B,CAAC;AAEF,SAAQ,MAAM,MAAd;EACE,KAAK;EACL,KAAK;AACH,SAAM,gBAAgB,0CAA0C;IAC9D,UAAU,WAAW,KAAK;IAC1B,cAAc,WAAW,KAAK;IAC9B,UAAU,MAAM;IACjB,CAAC;AACF;EAEF,KAAK;EACL,KAAK;AACH,SAAM,gBAAgB,8CAA8C;IAClE,UAAU,WAAW,KAAK;IAC1B,cAAc,WAAW,KAAK;IAC9B,UAAU,MAAM;IAChB,WAAW,MAAM;IAClB,CAAC;AACF;EAEF,QACE,OAAM,iBAAiB,MAAM;;AAGjC,KAAI,MAAM,aACR,OAAM,SAAS,YAAY;EACzB,UAAU,WAAW,KAAK;EAC1B,cAAc,WAAW,KAAK;EAC9B,WAAW,MAAM;EAClB,CAAC;AAGJ,QAAO,IAAI,SAAS,MAAM,EAAE,QAAQ,KAAK,CAAC;;AA4B5C,SAAS,gBAAgB,SAAiB,WAAmB,QAAgB;CAC3E,MAAM,SAAS,WAAW,UAAU,OAAO,CAAC,OAAO,QAAQ,CAAC,OAAO,MAAM;CACzE,MAAM,IAAI,OAAO,KAAK,QAAQ,MAAM;CACpC,MAAM,IAAI,OAAO,KAAK,WAAW,MAAM;AACvC,QAAO,EAAE,WAAW,EAAE,UAAU,gBAAgB,GAAG,EAAE;;AAGvD,eAAe,qBACb,OAC8C;AAC9C,QAAO,aAAa,YAAY,MAAM,SAAS,KAAK,UAAU,MAAM,IAAI;;AAG1E,eAAe,8BACb,cAC+B;CAC/B,MAAM,SAAS,gBAAgB;AAC/B,KAAI,CAAC,OAAQ,OAAM,IAAI,MAAM,8BAA8B,eAAe;AAC1E,QAAO;;AAGT,eAAe,gBAAgB,MAAc,OAAgC;AAC3E,OAAM,kBAAkB,QAAQ;EAAE;EAAM;EAAO,CAAC;;AAGlD,eAAe,iBAAiB,QAA4B;AAC1D,OAAM,oBAAoB,OAAO;EAC/B,OAAO;EACP,SAAS;EACV,CAAC;;AAGJ,MAAM,eAAe,EACnB,aAAa,EAAE,EAChB;AAED,MAAM,kBAAwD,EAAE;AAEhE,MAAM,oBAAoB,EACxB,SAAS,OAAO,aAAsC,IAGvD;AAED,MAAM,sBAAsB,EAC1B,QAAQ,OAAO,aAAsC,IAGtD"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import example from "./example.js";
+import { powensOAuthCallbackHandler } from "./handlers/oauth-callback.js";
+import { powensWebhookHandler } from "./handlers/webhook-handler.js";
+export { example, powensOAuthCallbackHandler, powensWebhookHandler };

package/dist/index.js

@@ -0,0 +1,6 @@
+import example_default from "./example.js";
+import { powensOAuthCallbackHandler } from "./handlers/oauth-callback.js";
+import { powensWebhookHandler } from "./handlers/webhook-handler.js";
+import "./docs/index.js";
+
+export { example_default as example, powensOAuthCallbackHandler, powensWebhookHandler };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@contractspec/example.openbanking-powens",
+  "version": "0.0.0-canary-20260113170453",
+  "description": "OpenBanking Powens example: OAuth callback + webhook handler patterns (provider + workflows).",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/openbanking-powens.docblock": "./dist/docs/openbanking-powens.docblock.js",
+    "./example": "./dist/example.js",
+    "./handlers/oauth-callback": "./dist/handlers/oauth-callback.js",
+    "./handlers/webhook-handler": "./dist/handlers/webhook-handler.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@contractspec/integration.providers-impls": "0.0.0-canary-20260113170453",
+    "@contractspec/lib.contracts": "0.0.0-canary-20260113170453"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "0.0.0-canary-20260113170453",
+    "@contractspec/tool.typescript": "0.0.0-canary-20260113170453",
+    "tsdown": "^0.19.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/openbanking-powens.docblock": "./dist/docs/openbanking-powens.docblock.js",
+      "./example": "./dist/example.js",
+      "./handlers/oauth-callback": "./dist/handlers/oauth-callback.js",
+      "./handlers/webhook-handler": "./dist/handlers/webhook-handler.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/openbanking-powens"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './openbanking-powens.docblock';

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

@@ -0,0 +1,28 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/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.`,
+  },
+];
+
+registerDocBlocks(blocks);

package/src/example.ts

@@ -0,0 +1,32 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+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 },
+  },
+});
+
+export default example;

package/src/handlers/oauth-callback.ts

@@ -0,0 +1,113 @@
+/**
+ * Example OAuth callback handler for Powens (open banking).
+ *
+ * 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';
+
+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
+  );
+}
+
+interface ExamplePowensSecrets {
+  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>;
+}
+
+async function getConnectionByState(
+  state: string
+): Promise<ExampleIntegrationConnection | null> {
+  const record = fakeDatabase.connections.find((conn) => conn.state === state);
+  return record ?? null;
+}
+
+async function getPowensSecretsForConnection(
+  connectionId: string
+): Promise<ExamplePowensSecrets> {
+  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 });
+}
+
+const fakeDatabase = {
+  connections: [] as (ExampleIntegrationConnection & { state: string })[],
+};
+
+const fakeSecretStore: Record<string, ExamplePowensSecrets> = {};
+
+const fakeWorkflowQueue = {
+  enqueue: async (_payload: Record<string, unknown>) => {
+    /* no-op */
+  },
+};

package/src/handlers/webhook-handler.ts

@@ -0,0 +1,147 @@
+/**
+ * Example Powens webhook handler (fetch-compatible).
+ *
+ * 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';
+
+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 });
+}
+
+interface PowensWebhookEvent {
+  type: string;
+  user_uuid: string;
+  connection_uuid: string;
+  account_uuid?: string;
+}
+
+interface ExamplePowensSecrets {
+  clientId: string;
+  clientSecret: string;
+  apiKey?: string;
+  webhookSecret: string;
+}
+
+interface ExampleIntegrationConnection {
+  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);
+}
+
+async function getConnectionByState(
+  state: string
+): Promise<ExampleIntegrationConnection | null> {
+  return fakeDatabase.connections.find((conn) => conn.state === state) ?? null;
+}
+
+async function getPowensSecretsForConnection(
+  connectionId: string
+): Promise<ExamplePowensSecrets> {
+  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 });
+}
+
+async function logUnmappedEvent(_event: PowensWebhookEvent) {
+  await fakeTelemetryLogger.record({
+    event: 'openbanking.webhook.unmapped',
+    payload: 'redacted',
+  });
+}
+
+const fakeDatabase = {
+  connections: [] as (ExampleIntegrationConnection & { state: string })[],
+};
+
+const fakeSecretStore: Record<string, ExamplePowensSecrets> = {};
+
+const fakeWorkflowQueue = {
+  enqueue: async (_payload: Record<string, unknown>) => {
+    /* no-op */
+  },
+};
+
+const fakeTelemetryLogger = {
+  record: async (_payload: Record<string, unknown>) => {
+    /* no-op */
+  },
+};

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './handlers/oauth-callback';
+export * from './handlers/webhook-handler';
+export { default as example } from './example';
+import './docs';

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@contractspec/tool.typescript/react-library.json",
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"],
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  }
+}
+
+