@jskit-ai/connectors-catalog 0.1.1

package/patterns/aws-storage-queries/example/integrations.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "files": {
+      "provider": "aws-s3",
+      "displayName": "Application files",
+      "accountMode": "shared",
+      "scopes": [
+        "read"
+      ],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:AWS_SECRET_ACCESS_KEY"
+      },
+      "settings": {
+        "region": "ap-southeast-2",
+        "bucket": "my-app-files",
+        "accessKeyIdRef": "env:AWS_ACCESS_KEY_ID"
+      }
+    },
+    "queries": {
+      "provider": "aws-athena",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:AWS_SECRET_ACCESS_KEY"
+      },
+      "settings": {
+        "region": "ap-southeast-2",
+        "accessKeyIdRef": "env:AWS_ACCESS_KEY_ID",
+        "workgroup": "reports",
+        "resultLocation": "s3://query-results/reports/"
+      }
+    }
+  }
+}

package/patterns/aws-storage-queries/example/s3-transfer.js

@@ -0,0 +1,34 @@
+// Application-owned composition: service.authorize must approve this exact key
+// for context. The same function works in a Node CLI or application backend.
+// Pass a bounded signal for both signing and the complete response-body read.
+export async function transferS3Object({ service, context, integrationId, key,
+  direction, body, signal, fetchImpl = globalThis.fetch }) {
+  if (!["download", "upload"].includes(direction)) throw new TypeError("Choose download or upload.");
+  if (!signal) throw new TypeError("Supply a transfer cancellation/timeout signal.");
+  if (direction === "upload" && !(body instanceof Blob || body instanceof ArrayBuffer || ArrayBuffer.isView(body))) {
+    throw new TypeError("Supply a Blob, ArrayBuffer or typed-array upload body.");
+  }
+  signal.throwIfAborted();
+  const signed = await service.invoke({ context, integrationId, signal,
+    operation: direction === "upload" ? "objects.uploadUrl" : "objects.downloadUrl",
+    input: { key } });
+  let response;
+  try {
+    response = await fetchImpl(signed.url, { method: signed.method,
+      ...(direction === "upload" ? { body } : {}), signal,
+      credentials: "omit", redirect: "error" });
+  } catch {
+    // Do not expose the URL through a network error/cause or retry a PUT whose
+    // outcome is unknown. The app decides whether to inspect and retry later.
+    throw new Error(direction === "upload"
+      ? "Upload interrupted; completion is unknown. Check the object before retrying."
+      : "Download interrupted. Request a fresh download when ready.");
+  }
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {});
+    throw new Error(`S3 ${direction} failed (HTTP ${response.status}). Check permissions and URL expiry.`);
+  }
+  // Keep binary downloads as a stream; the caller must await its consumption
+  // before announcing completion. Upload success means S3 acknowledged the PUT.
+  return response;
+}

package/patterns/event-delivery/PATTERN.md

@@ -0,0 +1,151 @@
+---
+id: connectors/event-delivery
+title: Authorized Inngest event delivery with portable files
+summary: Compose the shared connector runtime for event delivery while leaving workflow code and event policy with the application.
+keywords: connectors, integrations, inngest, events, workflows, files, cli
+requires: @jskit-ai/connectors-core, @jskit-ai/connectors-catalog
+---
+
+# Authorized Inngest event delivery with portable files
+
+## Use when
+
+An existing application or CLI must send an event to Inngest and inspect app
+metadata using separately owned Signing and Event Keys.
+
+## Do not use when
+
+This fragment does not execute or register workflow functions, implement an
+Inngest serve endpoint, configure schedules or provide application-user login.
+Those concerns belong to the app and its chosen Inngest SDK integration.
+
+## Product decisions
+
+Choose the connection owner, allowed event names, payload schema and stable
+business operation ID. Decide which authenticated users may trigger each event.
+Determine how the app will reconcile delivery uncertainty and report workflow
+progress independently of the connector's delivery receipt.
+
+## Invariants
+
+- Configuration and connection state remain text files.
+- Signing and Event Key values remain environment bindings, outside source.
+- Metadata verification never sends an event or verifies the Event Key.
+- Authorization sees the requested event before its Event Key is resolved.
+- An accepted event does not prove a function completed.
+- A cancelled request must not automatically replay a possibly accepted event.
+
+## Framework APIs
+
+Use the `api-key-connection` pattern's existing composition with
+`providers: [inngestProvider]`, imported from
+`@jskit-ai/connectors-catalog/server/inngest`. The JSKIT library owns validated
+requests, credential selection, responses, cancellation and file grants.
+
+## Example files
+
+`example/integrations.json` supplies the shared `workflows` slot. Provision
+`INNGEST_SIGNING_KEY` and `INNGEST_EVENT_KEY` in the backend environment and
+use the existing file-store protection and authenticated connection context.
+
+```js
+async function applicationConnectionPolicy(context, request) {
+  const owner = await workflowAccess.requireConnectionOwner(context, request.integrationId);
+  if (request.operation === "events.send") {
+    await workflowAccess.requireEventPermission(context, request.input);
+  }
+  return owner;
+}
+```
+
+`workflowAccess` is application-owned policy, not a JSKIT API. It must validate
+allowed names and payload ownership against authenticated state. It must also
+authorize connection management and metadata reads. Return a stable trusted
+`applicationId` and `subjectId`; do not trust owner IDs supplied by a browser.
+
+```js
+await connections.connectApiKey({ context, integrationId: "workflows" });
+// In an authorized application action, after validating report ownership:
+const receipt = await connections.invoke({
+  context, integrationId: "workflows", operation: "events.send", signal,
+  input: {
+    name: "app/report.requested",
+    id: `app/report.requested:${reportRequestId}`,
+    data: { reportRequestId }
+  }
+});
+// Record receipt.ids[0] as delivered; track workflow completion separately.
+```
+
+The application supplies `reportRequestId` from its validated business request.
+Inngest's deduplication window is finite; a stable ID is not a permanent
+exactly-once guarantee. Within an Inngest function, use the SDK's documented
+step event-sending primitive so delivery participates in durable execution.
+Do not replace SDK function orchestration with connector calls.
+
+## Variation points
+
+`settings.branchEnvironment` routes event delivery to a branch and does not
+change metadata query selection. `accountMode: "assistant"` requires the host's
+delegated event authority, including any explicit approval. A trusted operator
+CLI uses the same JSON and library without depending on editor storage.
+
+## Verification
+
+The provider's focused tests simulate metadata and event replies and use real
+encrypted file storage. The public-editor test exercises the same reference
+and branch settings. This source pattern does not generate or run a sample app;
+live event delivery and SDK function execution remain separate acceptance work.
+
+## Avoid
+
+Do not expose either key in browser code, send events as a connection probe,
+interpret delivery as completed work, permit arbitrary events through a shared
+public route, or retry after an ambiguous network failure without reconciliation.
+
+## Native functions and cron
+
+App-owned composition, using the native SDK's current `triggers` option
+([functions](https://www.inngest.com/docs/learn/inngest-functions),
+[cron](https://www.inngest.com/docs/guides/scheduled-functions),
+[serve adapters](https://www.inngest.com/docs/learn/serving-inngest-functions);
+reviewed 2026-09-13). Add `inngest` to the consuming application, not to JSKIT's
+connector package. Resolve the JSON slot's Env references before constructing
+its SDK client; standard names below match the example configuration.
+
+```js
+import { Inngest } from "inngest";
+import { fastifyPlugin } from "inngest/fastify";
+
+const workflows = new Inngest({ id: "reports", eventKey: process.env.INNGEST_EVENT_KEY });
+const report = workflows.createFunction(
+  { id: "requested-report", triggers: { event: "app/report.requested" } },
+  async ({ event, step }) => {
+    const id = event.data.reportRequestId;
+    if (typeof id !== "string" || !id) throw new Error("Missing report request ID");
+    return step.run("render-and-store", () => reports.renderRequestedReport(id));
+  }
+);
+const reconcile = workflows.createFunction(
+  { id: "reconcile-reports", triggers: { cron: "TZ=UTC 0 * * * *" } },
+  async ({ step }) => step.run("reconcile-due", () => reports.reconcileDueRequests())
+);
+// `fastify` is the app's existing server. The SDK validates signed requests
+// using INNGEST_SIGNING_KEY from the deployed application's environment.
+await fastify.register(fastifyPlugin, { client: workflows, functions: [report, reconcile] });
+```
+
+`reports` is the application's business service, not a library API. It loads
+persisted, previously authorized requests, enforces tenant boundaries and makes
+writes safe to retry. Do not trust an event's arbitrary user/tenant identifier
+as authorization. `step.run` may retry failed work; a durable step is not a
+substitute for idempotent business writes. Cron timezone is explicit; choose
+schedules with awareness of daylight-saving behavior.
+
+Expose the SDK route through the app's normal server composition, then deploy
+and sync its HTTPS `/api/inngest` URL in the selected Inngest environment.
+Keep the Signing Key private and let the native adapter verify signatures.
+JSKIT CLI users follow the same steps without Vibe64. Other stacks use native
+SDKs where available and the same event name/payload/Env contract; this example
+does not promise an SDK in every language. No function execution, cloud sync
+or generated application is performed by this reference pattern.

package/patterns/event-delivery/example/integrations.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "registrations": {},
+  "integrations": {
+    "workflows": {
+      "provider": "inngest",
+      "displayName": "Report workflows",
+      "accountMode": "shared",
+      "scopes": [],
+      "authentication": {
+        "method": "api-key",
+        "secretRef": "env:INNGEST_SIGNING_KEY"
+      },
+      "settings": { "eventKeyRef": "env:INNGEST_EVENT_KEY" }
+    }
+  }
+}

package/patterns/firebase-messaging/PATTERN.md

@@ -0,0 +1,156 @@
+---
+id: connectors/firebase-messaging
+title: Firebase messaging from a CLI or application backend
+summary: Wire service-account grants, file storage, explicit message actions and public browser settings without generating an application.
+keywords: connectors, integrations, firebase, fcm, service-account, jwt, notifications, push, vapid, cli, files
+requires: @jskit-ai/connectors-core, @jskit-ai/connectors-catalog
+---
+
+# Firebase messaging from a CLI or application backend
+
+## Use when
+
+Use this pattern for an application's Firebase sender. The provider package
+implements the service-account protocol and messaging operations; the core
+implements token persistence, renewal and ownership. The application supplies
+its existing authenticated identity, authorization, runtime directory and Env
+bindings. The CLI uses these same libraries. Do not copy their token manager
+or introduce an editor database.
+
+Read the packaged `docs/firebase-cloud-messaging.md` before provisioning. No
+OAuth callback exists for this credential mode. The application owner supplies
+the Firebase project and service account through its own Env bindings.
+
+## Do not use when
+
+Use another provider contract for Firebase Authentication, Firestore or Cloud
+Storage. This fragment does not provide those services or managed provisioning.
+
+## Product decisions
+
+Choose the target project, who may send which notifications, and whether the
+application needs browser enrollment or only existing targets. Decide where
+recipient/device associations belong in the application's existing storage.
+
+## Invariants
+
+Private service-account JSON remains on the server. Configuration stores its
+reference, stable project identity and public settings. Verify before reporting
+Connected; authorize every audience before sending. Preserve the existing file
+store and token lock instead of copying the grant implementation.
+
+## Framework APIs
+
+Use `parseIntegrationConfiguration`, `createConnectionService`,
+`createEnvironmentReferenceResolver`, `createFileConnectionStore`,
+`createCredentialProtection` and `firebaseCloudMessagingProvider` as shown below.
+The public helper is `firebaseCloudMessagingWebConfiguration`; the standard
+Feature action is `connectors.verifyServiceAccount`.
+
+## Example files
+
+The example module and inline fragments adapt to the application's existing
+source files. They are source guidance, not a generated application or template
+installation.
+
+Adapt this source fragment to the application's existing startup owner:
+
+[server/notifications.js](example/server/notifications.js) exports
+`openNotificationConnections({ configurationPath, runtimeDirectory, credentialKey, environment, authorizeConnectionOperation })`.
+It composes the existing libraries and returns the ordinary connection service.
+
+`credentialKey` is a private 32-byte `Uint8Array`, loaded from the application's
+secret owner, not a literal in generated source. `runtimeDirectory` is an
+absolute private path outside the repository. `environment` contains the
+service-account JSON string referenced by `integrations.json`; a path to that
+JSON file is not the credential value. An application with its own secret store
+can supply an equivalent `resolveReference` implementation.
+
+`authorizeConnectionOperation(context, request)` must obtain the real owner
+from trusted identity and return `{ applicationId, subjectId }` only after
+checking access. Shared senders use an authorized shared subject. Every
+`messages.send` requires checking `request.input.message` against the allowed
+recipient and content. A signed-in user or assistant must not gain arbitrary
+topic broadcasts merely by accessing this integration. Keep public and paid
+project assignments in host policy.
+
+## Explicit actions
+
+From the existing CLI command or server action, verify the configured sender:
+
+```js
+await connections.connectServiceAccount({
+  context: trustedContext, integrationId: "push", signal
+});
+```
+
+This checks a fixed topic with `validate_only: true`. It does not send a test
+notification. For an actual application message, build a bounded typed payload
+and authorize it before invoking the send operation:
+
+```js
+const message = {
+  fid: recipientInstallationId,
+  notification: { title: "Order ready", body: "Your order is ready." },
+  data: { orderId: String(order.id) }
+};
+await connections.invoke({ context: trustedContext, integrationId: "push",
+  operation: "messages.validate", input: { message }, signal });
+// Use the application's explicit send action and its authorization policy.
+await connections.invoke({ context: trustedContext, integrationId: "push",
+  operation: "messages.send", input: { message }, signal });
+```
+
+Validation does not authorize the later send and is not a delivery guarantee.
+Use exactly one target: `fid`, existing `token`, `topic` or `condition`. Prefer
+installation IDs when using the current Firebase SDK. Keep the installed SDK's
+enrollment contract consistent; do not mix registration-token and installation
+APIs. No automatic retry should wrap an ambiguous timed-out send. If the product
+needs retry scheduling, implement that behavior in its existing delivery owner.
+
+The standard JSKIT Feature is also available through
+`createConnectorsFeature(options)` and `connectors.verifyServiceAccount`.
+Product message operations belong in application actions that call `invoke`;
+never expose an arbitrary authenticated URL or unconstrained provider operation.
+
+## Variation points
+
+### Browser composition
+
+For a configuration with `clientMode: "web"`, use the pure library projection:
+
+```js
+import { firebaseCloudMessagingWebConfiguration } from "@jskit-ai/connectors-catalog/client/firebase-cloud-messaging";
+const { firebaseConfig, vapidKey } = firebaseCloudMessagingWebConfiguration(publicPushSettings);
+```
+
+Supply `firebaseConfig` to the application's Firebase initialization and
+`vapidKey` to its SDK registration call. Current documentation uses
+`register(messaging, { vapidKey })` and `onRegistered(messaging, callback)`;
+verify those exports against the version actually installed before wiring them.
+The callback passes the installation ID to an authenticated app endpoint that
+associates it with the correct user/device. Serve the service worker at the
+app's origin and request notification permission through an explicit UI action.
+The public configuration contains no private service-account data.
+
+On a custom-domain change, register the browser on the new origin and replace
+its installation association through the same authorized endpoint. Keep the
+stable application identity and project assignment. The server token exchange
+does not acquire a new OAuth callback just because an app uses another domain.
+
+## Verification
+
+Use a generated test key and an injected `fetchImpl` fixture. Verify JWT issuer,
+audience, expiry, scope and signature; inspect `validate_only` and payload
+targets; cover missing permissions, malformed receipts and cancellation. Use
+the actual file store to test restart and rotation. Form tests must check
+server/web mode changes, reference rejection, public values and file reload.
+These checks do not prove live delivery or browser subscription. Do not create
+a real project, key, subscription or notification as an incidental test.
+
+## Avoid
+
+Do not expose service-account JSON to the browser, confuse Firebase API keys
+with private service credentials, or choose the paid project from caller input.
+Do not treat an accepted message receipt as device delivery or automatically
+retry a send whose outcome is unknown.

package/patterns/firebase-messaging/example/server/notifications.js

@@ -0,0 +1,23 @@
+import { readFile } from "node:fs/promises";
+import { parseIntegrationConfiguration } from "@jskit-ai/connectors-core/shared/configuration";
+import { createConnectionService, createEnvironmentReferenceResolver } from "@jskit-ai/connectors-core/server";
+import { createFileConnectionStore, createCredentialProtection } from "@jskit-ai/connectors-core/server/file-storage";
+import { firebaseCloudMessagingProvider } from "@jskit-ai/connectors-catalog/server/firebase-cloud-messaging";
+
+export async function openNotificationConnections({
+  configurationPath, runtimeDirectory, credentialKey, environment,
+  authorizeConnectionOperation
+}) {
+  const providers = [firebaseCloudMessagingProvider];
+  const configuration = parseIntegrationConfiguration(
+    await readFile(configurationPath, "utf8"), { providers }
+  );
+  const protection = createCredentialProtection({
+    keys: { current: credentialKey }, activeKeyId: "current"
+  });
+  const store = createFileConnectionStore({ directory: runtimeDirectory, protection });
+  return createConnectionService({ configuration, providers, store,
+    resolveReference: createEnvironmentReferenceResolver(environment),
+    authorize: authorizeConnectionOperation
+  });
+}

package/patterns/google-ads-search/PATTERN.md

@@ -0,0 +1,92 @@
+---
+id: connectors/google-ads-search
+title: Existing-account Google Ads Search
+summary: Compose reviewed Search campaigns with project-owned Google OAuth and portable saved plans.
+keywords: google, ads, search, campaigns, conversion, cli, connectors
+requires: @jskit-ai/connectors-core, @jskit-ai/connectors-catalog
+---
+
+# Existing-account Google Ads Search
+
+## Use when
+
+Use the application's normal configuration, Env resolution, OAuth connection
+store and authenticated administrator policy. This is an optional application
+command composition fragment, not an editor dependency of the runtime library.
+
+## Framework APIs
+
+```js
+import { createGoogleAdsSearchService } from '@jskit-ai/connectors-catalog/server/google-ads-search';
+const ads = createGoogleAdsSearchService({ connections, configuration, context, integrationId });
+const review = await ads.preview(); // local and Google validation only
+// Only after the administrator reviews it:
+const created = await ads.create(review.reviewId); // starts PAUSED
+```
+
+`configuration.extensions.googleAdsSearch[integrationId]` holds the saved plan.
+Validate it with `validateGoogleAdsSearchPlan` from the package's shared
+`google-ads-search` export. Keep OAuth settings separate so campaign edits do not
+invalidate consent. The runtime has no Vibe64 protocol, frontend, Env injection or
+storage owner. CLI apps can call it directly. Normal `connections.authorize` must
+authorize the trusted application's advertising administrator for each operation;
+never accept a subject identity from a request body.
+
+For Vibe64, compose `example/ads-setup.js` into the app's existing Integration setup
+command and return exactly one JSON result on stdout. Derive `context` and the
+allowed integration ID from trusted command composition before calling the
+fragment. Keep connection status/connect/reconnect/disconnect operations intact.
+Read the public Vibe64 `application-google-ads.md` command contract when targeting
+that editor. Other frameworks implement its JSON/Env and operation contract with
+their native libraries; they do not execute this JavaScript fragment.
+
+The Search recipe supports only non-political manual-CPC campaigns with one ad
+group, phrase keywords and a website conversion goal. Account creation, PMax,
+Demand Gen, billing provisioning and automatic assistant tool attachment are not
+implemented. Google API validation does not establish account approval, website
+readiness or conversion-tag installation. The operator must verify those before
+the separately reviewed launch. Lost write responses are uncertain: inspect the
+provider instead of replaying the operation. Disconnect does not stop ad spend.
+
+## Do not use when
+
+Do not use this recipe to provision accounts, build PMax/Demand Gen campaigns or
+expose an unrestricted advertising endpoint to unauthenticated app users.
+
+## Product decisions
+
+Select the existing client account, website lead goal, location/language, budget,
+manual CPC bid and copy. Store them in the saved Search plan, not OAuth settings.
+Confirm non-political advertising and separately approve actual launch/spending.
+
+## Invariants
+
+The application owns the Google connection, trusted account authorization and
+persistent OAuth grants. Reviews include live account values and the saved plan.
+Creation is paused and atomic; launch rechecks the live review. Do not replay a
+write after an uncertain response. Disconnecting does not pause campaigns.
+
+## Example files
+
+`example/ads-setup.js` maps the optional editor command to the shared service. It
+contains no HTTP endpoint, credential resolution or trusted-identity inference.
+
+## Variation points
+
+CLI apps invoke the service directly. App-owned setup commands adapt the same
+service to their host. Other frameworks use native Google APIs and the same
+portable plan/operation semantics; they do not run this JavaScript fragment.
+
+## Verification
+
+Use controlled provider responses to check precise money strings, targeting,
+OAuth preservation, validate-only review, paused creation, stale-review rejection,
+explicit launch confirmation and no automatic replay of failed writes. Test
+normal application authorization before resolving credentials. Actual Google
+approval and conversion/billing readiness require operator verification.
+
+## Avoid
+
+Do not put secrets in JSON, stdout or chat. Do not execute conversion snippets in
+the editor, confuse OAuth consent with advertiser approval, or claim live account
+acceptance from fixture tests. Keep larger campaign types outside this recipe.

package/patterns/google-ads-search/example/ads-setup.js

@@ -0,0 +1,25 @@
+// Compose the service in the application's existing authenticated command owner.
+// No stdin value establishes the trusted application/administrator identity.
+export async function dispatchAdsSetup(request, service) {
+  if (request?.protocol !== "vibe64.integration-setup.command.v1" || typeof request.requestId !== "string" ||
+      !/^[A-Za-z0-9_-]{1,200}$/.test(request.requestId) || !request.ads || Array.isArray(request.ads) || typeof request.ads !== "object") {
+    throw new Error("Invalid advertising setup request.");
+  }
+  const args = request.ads;
+  let data;
+  switch (request.operation) {
+    case "ads-discover": data = await service.discover(args.customerId); break;
+    case "ads-targets": data = await service.targets(args.customerId, args.name); break;
+    case "ads-conversion": data = await service.createConversion(args); break;
+    case "ads-preview": data = await service.preview(); break;
+    case "ads-create": data = await service.create(args.reviewId); break;
+    case "ads-campaign": data = await service.campaign(args.campaignId); break;
+    case "ads-launch": data = await service.launch(args); break;
+    case "ads-pause": data = await service.pause(args.campaignId); break;
+    case "ads-report": data = await service.report(); break;
+    default: throw new Error("Unsupported advertising setup operation.");
+  }
+  const response = { protocol: request.protocol, requestId: request.requestId, status: "ads", operation: request.operation, data };
+  if (Buffer.byteLength(JSON.stringify(response)) > 32768) throw new Error("Advertising result exceeds the editor's display limit. Inspect Google Ads before repeating any write.");
+  return response;
+}