@jskit-ai/agent-docs 0.1.155 → 0.1.157

package/skills/jskit/references/patterns/connectors/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/skills/jskit/references/patterns/connectors/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/skills/jskit/references/patterns/connectors/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;
+}