@contractspec/example.openbanking-powens 1.57.0 → 1.58.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import example from "./example.js";
-import { powensOAuthCallbackHandler } from "./handlers/oauth-callback.js";
-import { powensWebhookHandler } from "./handlers/webhook-handler.js";
-export { example, powensOAuthCallbackHandler, powensWebhookHandler };
+export * from './handlers/oauth-callback';
+export * from './handlers/webhook-handler';
+export { default as example } from './example';
+import './docs';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,QAAQ,CAAC"}

package/dist/index.js

@@ -1,6 +1,229 @@
-import example from "./example.js";
-import { powensOAuthCallbackHandler } from "./handlers/oauth-callback.js";
-import { powensWebhookHandler } from "./handlers/webhook-handler.js";
-import "./docs/index.js";
+// @bun
+// src/docs/openbanking-powens.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    id: "docs.examples.openbanking-powens",
+    title: "Open Banking \u2014 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
+- OAuth callback handler: exchange auth code, map powens user, enqueue sync workflow.
+- Webhook handler: verify signature, route event \u2192 workflow, optionally refresh balances.
 
-export { example, powensOAuthCallbackHandler, powensWebhookHandler };
+## Guardrails
+- Secrets via secret providers/env only.
+- Verify webhook signatures.
+- Keep side effects explicit: enqueue workflows instead of mutating canonical stores inline.`
+  },
+  {
+    id: "docs.examples.openbanking-powens.usage",
+    title: "Open Banking \u2014 Powens \u2014 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
+- Wire \`powensOAuthCallbackHandler(req)\` at your OAuth redirect route.
+- Wire \`powensWebhookHandler(req)\` at your webhook route.
+
+## Notes
+- Replace the fake stores with your app-layer persistence.
+- Enqueue ContractSpec workflows for canonical upserts and telemetry.`
+  }
+];
+registerDocBlocks(blocks);
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var example = defineExample({
+  meta: {
+    key: "openbanking-powens",
+    version: "1.0.0",
+    title: "Open Banking \u2014 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 }
+  }
+});
+var example_default = example;
+
+// src/handlers/oauth-callback.ts
+import { PowensOpenBankingProvider } from "@contractspec/integration.providers-impls/impls/powens-openbanking";
+async function powensOAuthCallbackHandler(req) {
+  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,
+    baseUrl: connection.config.baseUrl
+  });
+  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);
+}
+async function getConnectionByState(state) {
+  const record = fakeDatabase.connections.find((conn) => conn.state === state);
+  return record ?? 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 });
+}
+var fakeDatabase = {
+  connections: []
+};
+var fakeSecretStore = {};
+var fakeWorkflowQueue = {
+  enqueue: async (_payload) => {}
+};
+
+// src/handlers/webhook-handler.ts
+import { createHmac, timingSafeEqual } from "crypto";
+import { PowensOpenBankingProvider as PowensOpenBankingProvider2 } from "@contractspec/integration.providers-impls/impls/powens-openbanking";
+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 getConnectionByState2(stateHeader);
+  if (!connection) {
+    return new Response("Unknown Powens state header", { status: 404 });
+  }
+  const secrets = await getPowensSecretsForConnection2(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 PowensOpenBankingProvider2({
+    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 enqueueWorkflow2("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 enqueueWorkflow2("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 getConnectionByState2(state) {
+  return fakeDatabase2.connections.find((conn) => conn.state === state) ?? null;
+}
+async function getPowensSecretsForConnection2(connectionId) {
+  const secret = fakeSecretStore2[connectionId];
+  if (!secret)
+    throw new Error(`Missing Powens secrets for ${connectionId}`);
+  return secret;
+}
+async function enqueueWorkflow2(name, input) {
+  await fakeWorkflowQueue2.enqueue({ name, input });
+}
+async function logUnmappedEvent(_event) {
+  await fakeTelemetryLogger.record({
+    event: "openbanking.webhook.unmapped",
+    payload: "redacted"
+  });
+}
+var fakeDatabase2 = {
+  connections: []
+};
+var fakeSecretStore2 = {};
+var fakeWorkflowQueue2 = {
+  enqueue: async (_payload) => {}
+};
+var fakeTelemetryLogger = {
+  record: async (_payload) => {}
+};
+export {
+  powensWebhookHandler,
+  powensOAuthCallbackHandler,
+  example_default as example
+};

package/dist/node/docs/index.js

@@ -0,0 +1,38 @@
+// src/docs/openbanking-powens.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    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
+- OAuth callback handler: exchange auth code, map powens user, enqueue sync workflow.
+- Webhook handler: verify signature, route event → workflow, optionally refresh balances.
+
+## Guardrails
+- Secrets via secret providers/env only.
+- Verify webhook signatures.
+- 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
+- Wire \`powensOAuthCallbackHandler(req)\` at your OAuth redirect route.
+- Wire \`powensWebhookHandler(req)\` at your webhook route.
+
+## Notes
+- Replace the fake stores with your app-layer persistence.
+- Enqueue ContractSpec workflows for canonical upserts and telemetry.`
+  }
+];
+registerDocBlocks(blocks);

package/dist/node/docs/openbanking-powens.docblock.js

@@ -0,0 +1,38 @@
+// src/docs/openbanking-powens.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    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
+- OAuth callback handler: exchange auth code, map powens user, enqueue sync workflow.
+- Webhook handler: verify signature, route event → workflow, optionally refresh balances.
+
+## Guardrails
+- Secrets via secret providers/env only.
+- Verify webhook signatures.
+- 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
+- Wire \`powensOAuthCallbackHandler(req)\` at your OAuth redirect route.
+- Wire \`powensWebhookHandler(req)\` at your webhook route.
+
+## Notes
+- Replace the fake stores with your app-layer persistence.
+- Enqueue ContractSpec workflows for canonical upserts and telemetry.`
+  }
+];
+registerDocBlocks(blocks);

package/dist/node/example.js

@@ -0,0 +1,33 @@
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var 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 }
+  }
+});
+var example_default = example;
+export {
+  example_default as default
+};

package/dist/node/handlers/oauth-callback.js

@@ -0,0 +1,64 @@
+// src/handlers/oauth-callback.ts
+import { PowensOpenBankingProvider } from "@contractspec/integration.providers-impls/impls/powens-openbanking";
+async function powensOAuthCallbackHandler(req) {
+  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,
+    baseUrl: connection.config.baseUrl
+  });
+  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);
+}
+async function getConnectionByState(state) {
+  const record = fakeDatabase.connections.find((conn) => conn.state === state);
+  return record ?? 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 });
+}
+var fakeDatabase = {
+  connections: []
+};
+var fakeSecretStore = {};
+var fakeWorkflowQueue = {
+  enqueue: async (_payload) => {}
+};
+export {
+  powensOAuthCallbackHandler
+};

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

@@ -0,0 +1,95 @@
+// src/handlers/webhook-handler.ts
+import { createHmac, timingSafeEqual } from "crypto";
+import { PowensOpenBankingProvider } from "@contractspec/integration.providers-impls/impls/powens-openbanking";
+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"
+  });
+}
+var fakeDatabase = {
+  connections: []
+};
+var fakeSecretStore = {};
+var fakeWorkflowQueue = {
+  enqueue: async (_payload) => {}
+};
+var fakeTelemetryLogger = {
+  record: async (_payload) => {}
+};
+export {
+  powensWebhookHandler
+};