@particle-academy/facebook-lead-ads-js 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to `@particle-academy/facebook-lead-ads-ui`,
+`@particle-academy/facebook-lead-ads-js`,
+`particle-academy/facebook-lead-ads-php` and `fancy-facebook-lead-ads`.
+
+The four packages share one version, because they are generated from one
+`provider/` definition and a version that meant something different in each
+would be a version nobody could reason about.
+
+## [0.1.0] — 2026-08-24
+
+First release.
+
+### Added
+
+- `leadgen` — a webhook trigger that starts when somebody submits a lead form.
+- `lead_get` — read one lead's answers by id. `GET /{leadId}`.
+- Fakers for both, so a flow can be wired before Meta has ever been contacted.
+
+### The delivery carries IDS, and no answers
+
+This is the shape worth understanding before wiring anything. Meta's `leadgen`
+webhook sends `leadgen_id`, `page_id`, `form_id`, `ad_id`, `adgroup_id` and
+`created_time` — and **nothing else**. The name, the email and the phone number
+are not in it. Reading them means a second call, which is what `lead_get` is.
+
+So the trigger's faker returns ids and nothing else too. A faker that helpfully
+invented an `email` would let somebody wire `{{ $json.email }}`, watch it work on
+the canvas, and discover on the first real lead that the field was never there.
+
+### The first `prefixed` signature header
+
+Meta signs every delivery with `X-Hub-Signature-256`, quoting its own docs,
+"preceded with `sha256=`". Stripe — the only webhook provider before this —
+packs a timestamp and signature into one compound header instead. So
+`verification.header.format: "prefixed"` had been declared in the vocabulary
+since Stripe and **driven by nothing**, which is exactly the shape this kit keeps
+finding: a declaration that validates clean and does nothing. It is exercised for
+real now, by a suite that runs the generated PHP and Python against it.
+
+### There is no timestamp, so there is no replay window
+
+Stripe signs `{timestamp}.{body}` and a delivery older than the tolerance is
+refused. Meta signs the body alone. **A captured delivery therefore stays valid
+forever**, and replay protection cannot come from the signature — it has to come
+from de-duplicating on `leadgen_id`. The definition says so rather than leaving
+`tolerance` absent, because an absence looks like an oversight.
+
+### One secret, two directions
+
+`appSecret` keys the `appsecret_proof` HMAC on **outgoing** calls and is what
+Meta signs **incoming** webhooks with. There is no per-endpoint webhook secret
+here the way there is in Stripe, where a leaked secret exposes one endpoint.
+
+The practical consequence: **rotating the app secret invalidates outgoing proofs
+and incoming signatures at the same instant.** A host that updates one credential
+field and not the other has broken the half it did not touch.
+
+### `leads_retrieval` fails quietly if you skip it
+
+Five scopes, and each is load-bearing:
+
+| | |
+|---|---|
+| `leads_retrieval` | reads a lead's `field_data`. **Without it the lead resolves with the personal data omitted rather than failing** — the reassuring failure. Also requires the app to pass Meta's Business Verification. |
+| `pages_manage_ads` | what Meta requires alongside it for lead access. |
+| `pages_manage_metadata` | what lets the app SUBSCRIBE to a Page's `leadgen` webhook. Without it the trigger never fires and nothing reports why. |
+| `pages_show_list`, `pages_read_engagement` | the standard Page pair. |
+
+Subscribing the app **per Page** (`POST /{pageId}/subscribed_apps`) is a separate
+step from configuring the webhook. A webhook configured but not subscribed
+delivers nothing, silently.
+
+### No sandbox — checked
+
+Meta's Lead Ads Testing Tool submits a **test lead against a real form on a real
+Page**, and it fires the real webhook. That is a way to exercise the integration,
+not a test estate: the lead lands where a real one does and is deleted by hand.
+No separate host, no separate account, no mode flag on the request.
+
+Everything this reads is real customer data belonging to a real advertiser.
+
+### Pinned to v25.0, not the newest
+
+Meta supports a Graph API version for roughly two years — v25.0 runs to
+2028-07-29 — and versioned changes land on the **newest** version immediately and
+reach older ones later. The newest buys a few months of runway and takes every
+breaking change first. An unversioned call silently gets the **oldest**
+still-supported version, which is why the segment is pinned at all.
+
+[0.1.0]: https://github.com/Fancy-Friends/facebook-lead-ads/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# Facebook Lead Ads
+
+Facebook Lead Ads for [fancy-flow][flow] — as **four imported, versioned packages**, one
+per runtime. Not vendored source: a copy cannot be upgraded, and third-party APIs
+change.
+
+[flow]: https://github.com/Particle-Academy/fancy-flow
+
+| Runtime | Package | Install |
+|---|---|---|
+| Authoring surface (every host) | `@particle-academy/facebook-lead-ads-ui` | `npm install @particle-academy/facebook-lead-ads-ui` |
+| Node | `@particle-academy/facebook-lead-ads-js` | `npm install @particle-academy/facebook-lead-ads-js` |
+| PHP 8.4+ | `particle-academy/facebook-lead-ads-php` | `composer require particle-academy/facebook-lead-ads-php` |
+| Python 3.11+ | `fancy-facebook-lead-ads` | `pip install fancy-facebook-lead-ads` |
+
+The `ui` package is the editor surface and is React on every host — a PHP or
+Python project installs it *and* its own runtime package, and never the `js` one.
+
+## What it costs you
+
+One dependency: `@particle-academy/fancy-connector-core` (or
+`particle-academy/fancy-connector-core` on Composer), which the `js` and `php`
+packages pull in themselves. The Python package has **zero** runtime
+dependencies.
+
+**No Facebook Lead Ads SDK.** Plain HTTP, deliberately: a vendor SDK is third-party code
+subject to the kit's full approval bar, and one per provider is hundreds of
+dependencies nobody is tracking.
+
+## Setting it up
+
+Everything below is generated from `provider/manifest.json`, so it cannot disagree with what the packages do.
+
+### Credentials
+
+A Facebook Lead Ads connection holds 4 values.
+
+**Two kinds of value, and mixing them up matters.** A `provider` credential is ONE value for the whole installation — an OAuth app's client secret serves every connected account. An `account` credential is one per connected account. A host that stores the second where it stores the first lets one account's credentials reach another's.
+
+| Field | Scope | Secret | Where it comes from |
+|---|---|---|---|
+| **App ID** | per installation | not secret | From the Meta app dashboard. ONE value for the whole installation. |
+| **App secret (OAuth)** | per installation | **secret** | The same app's client secret, used to exchange the authorization code. |
+| **App secret (proof and webhook signature)** | per installation | **secret** | TWO roles, one value. It keys the appsecret_proof HMAC on outgoing calls, and it is also what Meta signs INCOMING webhook deliveries with -- there is no per-endpoint webhook secret in the Graph API the way there is in Stripe. It is never sent in either direction. For a standard Meta app this is the same value as the OAuth client secret; it is declared separately because they are different roles, and an app that rotates one without the other should not silently break the other. |
+| **Page access token** | per connected account | **secret** | PER PAGE, not per user. Leads belong to a Page's forms, and Meta requires the token to be held by somebody who can advertise on the ad account. A long-lived page token lasts about 60 days and is re-authorised rather than refreshed. |
+
+### Authorising
+
+Facebook Lead Ads uses OAuth2 (authorization_code). The package DECLARES the exchange; the HOST performs it — a consent screen needs a browser, a redirect URI and somewhere to persist the result, and all three belong to the host.
+
+- **Authorize URL** — https://www.facebook.com/v25.0/dialog/oauth
+- **Token URL** — https://graph.facebook.com/v25.0/oauth/access_token
+- **Scopes** — `leads_retrieval`, `pages_manage_ads`, `pages_show_list`, `pages_read_engagement`, `pages_manage_metadata`
+- **Access token lifetime** — 5184000 seconds (60 days). A host that never refreshes works all afternoon and is broken by morning.
+
+**This flow issues NO refresh token.** A connection is RE-AUTHORISED rather than refreshed when the access token expires — checked, not assumed.
+
+### The estate
+
+**Facebook Lead Ads has no test estate, and somebody checked.** Everything this connector does is real. Use the faker to build against it.
+
+> Facebook Lead Ads has no sandbox. Meta's Lead Ads Testing Tool creates a test lead on the REAL form, which fires the real webhook and appears alongside real leads until somebody deletes it. Anything this reads is real customer data belonging to a real advertiser.
+
+## What it can do
+
+### Actions
+
+#### `lead_get` — Facebook lead
+
+Read one lead's answers by id. Pair this with the `leadgen` trigger, whose delivery carries only the id.
+
+`GET /{leadId}` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `leadId` | yes | From the `leadgen_id` on a `leadgen` delivery. It is not the form id and not the ad id -- both are also numeric, and passing one of those returns THAT object rather than an error. |
+
+### Triggers
+
+#### `leadgen` — Facebook lead
+
+Start when somebody submits a Facebook lead form. The delivery carries only IDS -- pair this with the `lead_get` action to read the answers.
+
+Delivered by webhook, and the signature is verified before anything runs.
+
+**You have to set this up with the provider first:**
+
+In the Meta app dashboard, add a Webhooks product, subscribe to the PAGE object and tick the `leadgen` field, and point the callback URL at the route your host mounts for this trigger. Meta first sends a GET carrying `hub.mode=subscribe`, `hub.verify_token` and `hub.challenge` -- the host must echo `hub.challenge` back as the body and check `hub.verify_token` against the value set in the dashboard, or the subscription is never activated. Then subscribe the app to each Page (`POST /{pageId}/subscribed_apps` with `subscribed_fields=leadgen`), which is a SEPARATE step: a webhook configured but not subscribed per Page delivers nothing and reports nothing.
+
+## Run it before you have credentials
+
+Every operation ships a **faker**, whether or not Facebook Lead Ads has a sandbox. Set a
+node's mode to `fake` and it returns the shape Facebook Lead Ads actually publishes — the
+same field names, deterministically — so you can wire the downstream nodes before
+touching an account, a key, or a network.
+
+## This repository is generated
+
+`provider/` is the source. Everything under `packages/` is emitted from it and
+**must not be hand-edited** — CI regenerates and diffs on every push, and the
+next protocol sync destroys anything it finds. See [`AGENTS.md`](AGENTS.md).
+
+## Two namespaces, which do not match on purpose
+
+The repo is `github.com/Fancy-Friends/facebook-lead-ads`; the packages publish under
+`particle-academy`. Nothing derives one from the other — the names come from
+weaver's `friends.json` and nowhere else.
+
+## Licence
+
+MIT.

package/dist/chunk-JVNM4F6J.js

@@ -0,0 +1,137 @@
+import { createHmac } from 'crypto';
+import { callConnector, verifyDelivery } from '@particle-academy/fancy-connector-core';
+
+// src/faker.ts
+function fakeLeadGet({ config, fake }) {
+  return {
+    "id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "created_time": "2026-08-24T09:15:00+0000",
+    "ad_id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "form_id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "field_data": [
+      {
+        "name": "full_name",
+        "values": [
+          "Ada Lovelace"
+        ]
+      },
+      {
+        "name": "email",
+        "values": [
+          "ada@example.test"
+        ]
+      },
+      {
+        "name": "phone_number",
+        "values": [
+          "+15550100"
+        ]
+      },
+      {
+        "name": "what_are_you_interested_in",
+        "values": [
+          "Enterprise plan"
+        ]
+      }
+    ]
+  };
+}
+function fakeLeadgen({ config, fake }) {
+  const boundLeadid = Array.from({ length: 15 }, () => fake.int(0, 9)).join("");
+  return {
+    "leadgen_id": boundLeadid,
+    "page_id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "form_id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "ad_id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "adgroup_id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "created_time": 1787577300
+  };
+}
+var facebookLeadAdsFaker = (operation, request) => {
+  switch (operation) {
+    case "lead_get":
+      return fakeLeadGet(request);
+    case "leadgen":
+      return fakeLeadgen(request);
+    default:
+      throw new Error(
+        `facebook_lead_ads: no fake response is defined for "${operation}". Add a fixture under provider/fixtures/ and regenerate \u2014 a connector without a faker cannot be developed against, tested, or demonstrated.`
+      );
+  }
+};
+var CONNECTOR_API_VERSION = 1;
+var FACEBOOK_LEAD_ADS_BASE_URLS = {
+  "live": "https://graph.facebook.com/v25.0"
+};
+var FACEBOOK_LEAD_ADS_REQUIRES = [
+  "pageAccessToken",
+  "appSecret",
+  "clientId",
+  "clientSecret"
+];
+function facebookLeadAdsAuthorize(credentials, request, _mode) {
+  const url = new URL(request.url);
+  url.searchParams.set("access_token", String(credentials.pageAccessToken ?? ""));
+  const proof = createHmac("sha256", String(credentials.appSecret ?? "")).update(String(credentials.pageAccessToken ?? "")).digest("hex");
+  url.searchParams.set("appsecret_proof", proof);
+  request.url = url.toString();
+}
+var FACEBOOK_LEAD_ADS = {
+  service: "facebook_lead_ads",
+  title: "Facebook Lead Ads",
+  sandbox: "none",
+  baseUrls: { ...FACEBOOK_LEAD_ADS_BASE_URLS },
+  requires: [...FACEBOOK_LEAD_ADS_REQUIRES],
+  authorize: facebookLeadAdsAuthorize,
+  faker: facebookLeadAdsFaker
+};
+var LEAD_GET_OPERATION = "lead_get";
+async function facebookLeadAdsLeadGet(options) {
+  const config = options.config ?? {};
+  if (config.leadId === void 0 || config.leadId === null || config.leadId === "") {
+    throw new Error(`lead_get: "leadId" is required (Lead ID).`);
+  }
+  return callConnector(FACEBOOK_LEAD_ADS, {
+    operation: LEAD_GET_OPERATION,
+    config,
+    input: options.input,
+    ...options.credentials === void 0 ? {} : { credentials: options.credentials },
+    ...options.mode === void 0 ? {} : { mode: options.mode },
+    ...options.connectionId === void 0 ? {} : { connectionId: options.connectionId },
+    ...options.attempts === void 0 ? {} : { attempts: options.attempts },
+    ...options.transport === void 0 ? {} : { transport: options.transport },
+    request: {
+      method: "GET",
+      path: `/${encodeURIComponent(String(config.leadId))}`,
+      query: {}
+    }
+  });
+}
+var FACEBOOK_LEAD_ADS_LEADGEN_SIGNATURE_HEADER = "X-Hub-Signature-256";
+var FACEBOOK_LEAD_ADS_LEADGEN_SCHEME = {
+  algorithm: "SHA-256",
+  payload: (raw, timestamp) => raw,
+  encoding: "hex"
+};
+function parseFacebookLeadAdsSignature(raw) {
+  return { signature: raw.startsWith("sha256=") ? raw.slice(7) : raw };
+}
+var FACEBOOK_LEAD_ADS_LEADGEN = {
+  service: "facebook_lead_ads",
+  operation: "leadgen",
+  delivery: "webhook",
+  setup: "In the Meta app dashboard, add a Webhooks product, subscribe to the PAGE object and tick the `leadgen` field, and point the callback URL at the route your host mounts for this trigger. Meta first sends a GET carrying `hub.mode=subscribe`, `hub.verify_token` and `hub.challenge` -- the host must echo `hub.challenge` back as the body and check `hub.verify_token` against the value set in the dashboard, or the subscription is never activated. Then subscribe the app to each Page (`POST /{pageId}/subscribed_apps` with `subscribed_fields=leadgen`), which is a SEPARATE step: a webhook configured but not subscribed per Page delivers nothing and reports nothing.",
+  verification: {
+    signatureHeader: FACEBOOK_LEAD_ADS_LEADGEN_SIGNATURE_HEADER,
+    scheme: FACEBOOK_LEAD_ADS_LEADGEN_SCHEME,
+    parse: parseFacebookLeadAdsSignature
+  },
+  faker: facebookLeadAdsFaker
+};
+function verifyFacebookLeadAdsDelivery(delivery, appSecret, now) {
+  return verifyDelivery(FACEBOOK_LEAD_ADS_LEADGEN, delivery, appSecret, now);
+}
+
+export { CONNECTOR_API_VERSION, FACEBOOK_LEAD_ADS, FACEBOOK_LEAD_ADS_BASE_URLS, FACEBOOK_LEAD_ADS_LEADGEN, FACEBOOK_LEAD_ADS_LEADGEN_SCHEME, FACEBOOK_LEAD_ADS_LEADGEN_SIGNATURE_HEADER, FACEBOOK_LEAD_ADS_REQUIRES, LEAD_GET_OPERATION, facebookLeadAdsAuthorize, facebookLeadAdsFaker, facebookLeadAdsLeadGet, parseFacebookLeadAdsSignature, verifyFacebookLeadAdsDelivery };
+//# sourceMappingURL=chunk-JVNM4F6J.js.map
+//# sourceMappingURL=chunk-JVNM4F6J.js.map

package/dist/chunk-JVNM4F6J.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/faker.ts","../src/service.ts","../src/actions/lead-get.ts","../src/triggers/leadgen.ts"],"names":[],"mappings":"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","file":"chunk-JVNM4F6J.js","sourcesContent":["/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/fixtures/ by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/fixtures/ (or weaver's template/) and regenerate:\n *\n *     npm run provider -- facebook_lead_ads\n */\n\n/**\n * The Facebook Lead Ads faker.\n *\n * Shapes, not behaviour: the goal is that a downstream node sees the field\n * NAMES Facebook Lead Ads actually publishes, so an author can wire {{\n * $json.data.id }} against a fake and have it keep working against the real\n * thing.\n *\n * Deterministic — same inputs, same output. A faker returning a fresh uuid\n * every call cannot be asserted on, so its fixtures degrade to \"it did not\n * throw\", which is the assertion that catches nothing.\n */\n\nimport type { ConnectorFaker, FakeRequest } from \"@particle-academy/fancy-connector-core\";\n\nfunction fakeLeadGet({ config, fake }: FakeRequest): unknown {\n  return {\n    \"id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"created_time\": \"2026-08-24T09:15:00+0000\",\n    \"ad_id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"form_id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"field_data\": [\n      {\n        \"name\": \"full_name\",\n        \"values\": [\n          \"Ada Lovelace\",\n        ],\n      },\n      {\n        \"name\": \"email\",\n        \"values\": [\n          \"ada@example.test\",\n        ],\n      },\n      {\n        \"name\": \"phone_number\",\n        \"values\": [\n          \"+15550100\",\n        ],\n      },\n      {\n        \"name\": \"what_are_you_interested_in\",\n        \"values\": [\n          \"Enterprise plan\",\n        ],\n      },\n    ],\n  };\n}\n\nfunction fakeLeadgen({ config, fake }: FakeRequest): unknown {\n  const boundLeadid = Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\");\n\n  return {\n    \"leadgen_id\": boundLeadid,\n    \"page_id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"form_id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"ad_id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"adgroup_id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"created_time\": 1787577300,\n  };\n}\n\nexport const facebookLeadAdsFaker: ConnectorFaker = (operation, request) => {\n  switch (operation) {\n    case \"lead_get\":\n      return fakeLeadGet(request);\n\n    case \"leadgen\":\n      return fakeLeadgen(request);\n\n    default:\n      // A faker asked for an operation it has no shape for must SAY so. Making\n      // something up would produce a green run whose output silently has none\n      // of the fields the author is about to reference.\n      throw new Error(\n        `facebook_lead_ads: no fake response is defined for \"${operation}\". ` +\n          \"Add a fixture under provider/fixtures/ and regenerate — a connector without a faker \" +\n          \"cannot be developed against, tested, or demonstrated.\",\n      );\n  }\n};\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/manifest.json by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/manifest.json (or weaver's template/) and regenerate:\n *\n *     npm run provider -- facebook_lead_ads\n */\n\n/**\n * Facebook Lead Ads, as one service descriptor shared by every Facebook Lead\n * Ads operation.\n *\n * @particle-academy/fancy-connector-core carries what is true of ALL\n * connectors. This carries what is true of Facebook Lead Ads: its base URL,\n * its auth scheme, its idempotency header, and its faker.\n *\n * ## The sandbox trap, written down where it is used\n *\n * Facebook Lead Ads has no sandbox. Meta's Lead Ads Testing Tool creates a\n * test lead on the REAL form, which fires the real webhook and appears\n * alongside real leads until somebody deletes it. Anything this reads is real\n * customer data belonging to a real advertiser.\n */\n\nimport type { ConnectorMode, PreparedRequest, ServiceDescriptor } from \"@particle-academy/fancy-connector-core\";\n\nimport { facebookLeadAdsFaker } from \"./faker.js\";\nimport { createHmac } from \"node:crypto\";\n\n/**\n * The connector API version this package was GENERATED against.\n *\n * A literal, never imported. An imported constant lets an upgrade rewrite the\n * very claim it exists to detect, after which the copy agrees with itself\n * forever.\n */\nexport const CONNECTOR_API_VERSION = 1;\n\nexport const FACEBOOK_LEAD_ADS_BASE_URLS = {\n  \"live\": \"https://graph.facebook.com/v25.0\"\n} as const;\n\n/** Credential keys a remote call cannot proceed without. */\nexport const FACEBOOK_LEAD_ADS_REQUIRES = [\n  \"pageAccessToken\",\n  \"appSecret\",\n  \"clientId\",\n  \"clientSecret\"\n] as const;\n\n/**\n * Apply Facebook Lead Ads's auth scheme to an outgoing request.\n *\n * Same as facebook-pages: Meta takes the token as a QUERY PARAMETER, and\n * appsecret_proof has to go in the query regardless, so both live in one place\n * and a request stays readable in a log.\n *\n * The mode is passed in because for some providers auth and estate are the\n * same decision expressed in the URL; here it is unused, and saying so is\n * cheaper than wondering later whether it was forgotten.\n */\nexport function facebookLeadAdsAuthorize(\n  credentials: Record<string, string | undefined>,\n  request: PreparedRequest,\n  _mode: ConnectorMode,\n): void {\n  const url = new URL(request.url);\n\n  url.searchParams.set(\"access_token\", String(credentials.pageAccessToken ?? \"\"));\n\n  const proof = createHmac(\"sha256\", String(credentials.appSecret ?? \"\"))\n    .update(String(credentials.pageAccessToken ?? \"\"))\n    .digest(\"hex\");\n\n  url.searchParams.set(\"appsecret_proof\", proof);\n  request.url = url.toString();\n}\n\n/** The Facebook Lead Ads service, for the TypeScript runtime. */\nexport const FACEBOOK_LEAD_ADS: ServiceDescriptor = {\n  service: \"facebook_lead_ads\",\n  title: \"Facebook Lead Ads\",\n  sandbox: \"none\",\n  baseUrls: { ...FACEBOOK_LEAD_ADS_BASE_URLS },\n  requires: [...FACEBOOK_LEAD_ADS_REQUIRES],\n  authorize: facebookLeadAdsAuthorize,\n  faker: facebookLeadAdsFaker,\n};\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/actions/lead-get.json by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/actions/lead-get.json (or weaver's template/) and regenerate:\n *\n *     npm run provider -- facebook_lead_ads\n */\n\n/**\n * Read one lead's answers by id. Pair this with the `leadgen` trigger, whose\n * delivery carries only the id.\n *\n * GET /{leadId} —\n * https://developers.facebook.com/docs/marketing-api/guides/lead-ads/retrieving\n *\n * Notice what is NOT here: no key, no base URL, no mode check, no retry loop,\n * no fake/real branch. This describes the request; callConnector resolves the\n * connection, picks the estate, and either calls Facebook Lead Ads or calls\n * the faker.\n */\n\nimport {\n  callConnector,\n  type ConnectorResult,\n  type RequestedMode,\n  type Transport,\n} from \"@particle-academy/fancy-connector-core\";\nimport { FACEBOOK_LEAD_ADS } from \"../service.js\";\n\nexport const LEAD_GET_OPERATION = \"lead_get\";\n\nexport type LeadGetOptions = {\n  /** The node's resolved config. Keys: leadId. */\n  config: Record<string, unknown>;\n  credentials?: Record<string, string | undefined>;\n  mode?: RequestedMode;\n  connectionId?: string | null;\n  input?: unknown;\n  attempts?: number;\n  /** Override the transport. The only way to exercise this without a network. */\n  transport?: Transport;\n};\n\nexport async function facebookLeadAdsLeadGet(options: LeadGetOptions): Promise<ConnectorResult> {\n  const config = options.config ?? {};\n\n  if (config.leadId === undefined || config.leadId === null || config.leadId === \"\") {\n    throw new Error(`lead_get: \"leadId\" is required (Lead ID).`);\n  }\n\n  return callConnector(FACEBOOK_LEAD_ADS, {\n    operation: LEAD_GET_OPERATION,\n    config,\n    input: options.input,\n    ...(options.credentials === undefined ? {} : { credentials: options.credentials }),\n    ...(options.mode === undefined ? {} : { mode: options.mode }),\n    ...(options.connectionId === undefined ? {} : { connectionId: options.connectionId }),\n    ...(options.attempts === undefined ? {} : { attempts: options.attempts }),\n    ...(options.transport === undefined ? {} : { transport: options.transport }),\n    request: {\n      method: \"GET\",\n      path: `/${encodeURIComponent(String(config.leadId))}`,\n      query: {},\n    },\n  });\n}\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/triggers/leadgen.json by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/triggers/leadgen.json (or weaver's template/) and regenerate:\n *\n *     npm run provider -- facebook_lead_ads\n */\n\n/**\n * Facebook Lead Ads's webhook trigger — the delivery contract.\n *\n * Kept beside the service descriptor rather than inside a node, because a\n * signature scheme is a fact about FACEBOOK LEAD ADS. Two Facebook Lead Ads\n * triggers must not be able to disagree about how a delivery is verified.\n */\n\nimport { verifyDelivery, type HmacScheme, type InboundDelivery, type TriggerDescriptor, type WebhookVerification } from \"@particle-academy/fancy-connector-core\";\nimport { facebookLeadAdsFaker } from \"../faker.js\";\n\nexport const FACEBOOK_LEAD_ADS_LEADGEN_SIGNATURE_HEADER = \"X-Hub-Signature-256\";\n\nexport const FACEBOOK_LEAD_ADS_LEADGEN_SCHEME: HmacScheme = {\n  algorithm: \"SHA-256\",\n  payload: (raw, timestamp) => raw,\n  encoding: \"hex\",\n};\n\n/** Strip the `sha256=` prefix the provider sends. */\nexport function parseFacebookLeadAdsSignature(raw: string): { signature?: string } {\n  return { signature: raw.startsWith(\"sha256=\") ? raw.slice(7) : raw };\n}\n\nexport const FACEBOOK_LEAD_ADS_LEADGEN: TriggerDescriptor = {\n  service: \"facebook_lead_ads\",\n  operation: \"leadgen\",\n  delivery: \"webhook\",\n  setup:\n    \"In the Meta app dashboard, add a Webhooks product, subscribe to the PAGE object and tick the `leadgen` field, and point the callback URL at the route your host mounts for this trigger. Meta first sends a GET carrying `hub.mode=subscribe`, `hub.verify_token` and `hub.challenge` -- the host must echo `hub.challenge` back as the body and check `hub.verify_token` against the value set in the dashboard, or the subscription is never activated. Then subscribe the app to each Page (`POST /{pageId}/subscribed_apps` with `subscribed_fields=leadgen`), which is a SEPARATE step: a webhook configured but not subscribed per Page delivers nothing and reports nothing.\",\n  verification: {\n    signatureHeader: FACEBOOK_LEAD_ADS_LEADGEN_SIGNATURE_HEADER,\n    scheme: FACEBOOK_LEAD_ADS_LEADGEN_SCHEME,\n    parse: parseFacebookLeadAdsSignature,\n  },\n  faker: facebookLeadAdsFaker,\n};\n\n/**\n * Verify one inbound Facebook Lead Ads delivery.\n *\n * The host calls this BEFORE starting a run, with the body exactly as\n * received. Re-serialised JSON changes key order and whitespace, and produces\n * a mismatch that looks precisely like a wrong secret — hours of debugging the\n * wrong thing.\n *\n * The secret is the connection's `appSecret`.\n */\nexport function verifyFacebookLeadAdsDelivery(\n  delivery: InboundDelivery,\n  appSecret: string | undefined,\n  now?: number,\n): Promise<WebhookVerification> {\n  return verifyDelivery(FACEBOOK_LEAD_ADS_LEADGEN, delivery, appSecret, now);\n}\n"]}

package/dist/flow.cjs

@@ -0,0 +1,174 @@
+'use strict';
+
+var fancyConnectorCore = require('@particle-academy/fancy-connector-core');
+var crypto = require('crypto');
+var facebookLeadAdsUi = require('@particle-academy/facebook-lead-ads-ui');
+
+// src/flow.ts
+
+// src/faker.ts
+function fakeLeadGet({ config, fake }) {
+  return {
+    "id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "created_time": "2026-08-24T09:15:00+0000",
+    "ad_id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "form_id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "field_data": [
+      {
+        "name": "full_name",
+        "values": [
+          "Ada Lovelace"
+        ]
+      },
+      {
+        "name": "email",
+        "values": [
+          "ada@example.test"
+        ]
+      },
+      {
+        "name": "phone_number",
+        "values": [
+          "+15550100"
+        ]
+      },
+      {
+        "name": "what_are_you_interested_in",
+        "values": [
+          "Enterprise plan"
+        ]
+      }
+    ]
+  };
+}
+function fakeLeadgen({ config, fake }) {
+  const boundLeadid = Array.from({ length: 15 }, () => fake.int(0, 9)).join("");
+  return {
+    "leadgen_id": boundLeadid,
+    "page_id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "form_id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "ad_id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "adgroup_id": Array.from({ length: 15 }, () => fake.int(0, 9)).join(""),
+    "created_time": 1787577300
+  };
+}
+var facebookLeadAdsFaker = (operation, request) => {
+  switch (operation) {
+    case "lead_get":
+      return fakeLeadGet(request);
+    case "leadgen":
+      return fakeLeadgen(request);
+    default:
+      throw new Error(
+        `facebook_lead_ads: no fake response is defined for "${operation}". Add a fixture under provider/fixtures/ and regenerate \u2014 a connector without a faker cannot be developed against, tested, or demonstrated.`
+      );
+  }
+};
+var FACEBOOK_LEAD_ADS_BASE_URLS = {
+  "live": "https://graph.facebook.com/v25.0"
+};
+var FACEBOOK_LEAD_ADS_REQUIRES = [
+  "pageAccessToken",
+  "appSecret",
+  "clientId",
+  "clientSecret"
+];
+function facebookLeadAdsAuthorize(credentials, request, _mode) {
+  const url = new URL(request.url);
+  url.searchParams.set("access_token", String(credentials.pageAccessToken ?? ""));
+  const proof = crypto.createHmac("sha256", String(credentials.appSecret ?? "")).update(String(credentials.pageAccessToken ?? "")).digest("hex");
+  url.searchParams.set("appsecret_proof", proof);
+  request.url = url.toString();
+}
+var FACEBOOK_LEAD_ADS = {
+  service: "facebook_lead_ads",
+  title: "Facebook Lead Ads",
+  sandbox: "none",
+  baseUrls: { ...FACEBOOK_LEAD_ADS_BASE_URLS },
+  requires: [...FACEBOOK_LEAD_ADS_REQUIRES],
+  authorize: facebookLeadAdsAuthorize,
+  faker: facebookLeadAdsFaker
+};
+var LEAD_GET_OPERATION = "lead_get";
+async function facebookLeadAdsLeadGet(options) {
+  const config = options.config ?? {};
+  if (config.leadId === void 0 || config.leadId === null || config.leadId === "") {
+    throw new Error(`lead_get: "leadId" is required (Lead ID).`);
+  }
+  return fancyConnectorCore.callConnector(FACEBOOK_LEAD_ADS, {
+    operation: LEAD_GET_OPERATION,
+    config,
+    input: options.input,
+    ...options.credentials === void 0 ? {} : { credentials: options.credentials },
+    ...options.mode === void 0 ? {} : { mode: options.mode },
+    ...options.connectionId === void 0 ? {} : { connectionId: options.connectionId },
+    ...options.attempts === void 0 ? {} : { attempts: options.attempts },
+    ...options.transport === void 0 ? {} : { transport: options.transport },
+    request: {
+      method: "GET",
+      path: `/${encodeURIComponent(String(config.leadId))}`,
+      query: {}
+    }
+  });
+}
+var FACEBOOK_LEAD_ADS_LEADGEN_SIGNATURE_HEADER = "X-Hub-Signature-256";
+var FACEBOOK_LEAD_ADS_LEADGEN_SCHEME = {
+  algorithm: "SHA-256",
+  payload: (raw, timestamp) => raw,
+  encoding: "hex"
+};
+function parseFacebookLeadAdsSignature(raw) {
+  return { signature: raw.startsWith("sha256=") ? raw.slice(7) : raw };
+}
+var FACEBOOK_LEAD_ADS_LEADGEN = {
+  service: "facebook_lead_ads",
+  operation: "leadgen",
+  delivery: "webhook",
+  setup: "In the Meta app dashboard, add a Webhooks product, subscribe to the PAGE object and tick the `leadgen` field, and point the callback URL at the route your host mounts for this trigger. Meta first sends a GET carrying `hub.mode=subscribe`, `hub.verify_token` and `hub.challenge` -- the host must echo `hub.challenge` back as the body and check `hub.verify_token` against the value set in the dashboard, or the subscription is never activated. Then subscribe the app to each Page (`POST /{pageId}/subscribed_apps` with `subscribed_fields=leadgen`), which is a SEPARATE step: a webhook configured but not subscribed per Page delivers nothing and reports nothing.",
+  verification: {
+    signatureHeader: FACEBOOK_LEAD_ADS_LEADGEN_SIGNATURE_HEADER,
+    scheme: FACEBOOK_LEAD_ADS_LEADGEN_SCHEME,
+    parse: parseFacebookLeadAdsSignature
+  },
+  faker: facebookLeadAdsFaker
+};
+
+// src/flow.ts
+var facebookLeadAdsLeadExecutor = async (ctx) => {
+  const config = ctx.node.data?.config ?? {};
+  const result = await facebookLeadAdsLeadGet({
+    config,
+    input: ctx.inputs?.in
+  });
+  ctx.emit({
+    type: "log",
+    level: "info",
+    nodeId: ctx.node.id,
+    message: `facebook_lead_ads lead_get ${result.data?.id} (${result.mode})`
+  });
+  return { __port: "out", value: result };
+};
+var facebookLeadAdsWebhookTriggerExecutor = async (ctx) => {
+  const config = ctx.node.data?.config ?? {};
+  const connection = fancyConnectorCore.resolveConnection({
+    service: FACEBOOK_LEAD_ADS.service,
+    operation: "leadgen",
+    sandbox: FACEBOOK_LEAD_ADS.sandbox,
+    baseUrls: FACEBOOK_LEAD_ADS.baseUrls,
+    requires: FACEBOOK_LEAD_ADS.requires,
+    connectionId: typeof config.connection === "string" ? config.connection : null,
+    requested: typeof config.mode === "string" ? config.mode : null
+  });
+  const event = fancyConnectorCore.triggerEvent(FACEBOOK_LEAD_ADS_LEADGEN, connection, ctx.inputs?.in, config);
+  return { __port: "out", value: event };
+};
+var FACEBOOK_LEAD_ADS_RUNNABLE_KINDS = [
+  { ...facebookLeadAdsUi.facebookLeadAdsLeadKind, executor: facebookLeadAdsLeadExecutor },
+  { ...facebookLeadAdsUi.facebookLeadAdsWebhookTriggerKind, executor: facebookLeadAdsWebhookTriggerExecutor }
+];
+
+exports.FACEBOOK_LEAD_ADS_RUNNABLE_KINDS = FACEBOOK_LEAD_ADS_RUNNABLE_KINDS;
+exports.facebookLeadAdsLeadExecutor = facebookLeadAdsLeadExecutor;
+exports.facebookLeadAdsWebhookTriggerExecutor = facebookLeadAdsWebhookTriggerExecutor;
+//# sourceMappingURL=flow.cjs.map
+//# sourceMappingURL=flow.cjs.map

package/dist/flow.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/faker.ts","../src/service.ts","../src/actions/lead-get.ts","../src/triggers/leadgen.ts","../src/flow.ts"],"names":["createHmac","callConnector","resolveConnection","triggerEvent","facebookLeadAdsLeadKind","facebookLeadAdsWebhookTriggerKind"],"mappings":"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","file":"flow.cjs","sourcesContent":["/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/fixtures/ by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/fixtures/ (or weaver's template/) and regenerate:\n *\n *     npm run provider -- facebook_lead_ads\n */\n\n/**\n * The Facebook Lead Ads faker.\n *\n * Shapes, not behaviour: the goal is that a downstream node sees the field\n * NAMES Facebook Lead Ads actually publishes, so an author can wire {{\n * $json.data.id }} against a fake and have it keep working against the real\n * thing.\n *\n * Deterministic — same inputs, same output. A faker returning a fresh uuid\n * every call cannot be asserted on, so its fixtures degrade to \"it did not\n * throw\", which is the assertion that catches nothing.\n */\n\nimport type { ConnectorFaker, FakeRequest } from \"@particle-academy/fancy-connector-core\";\n\nfunction fakeLeadGet({ config, fake }: FakeRequest): unknown {\n  return {\n    \"id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"created_time\": \"2026-08-24T09:15:00+0000\",\n    \"ad_id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"form_id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"field_data\": [\n      {\n        \"name\": \"full_name\",\n        \"values\": [\n          \"Ada Lovelace\",\n        ],\n      },\n      {\n        \"name\": \"email\",\n        \"values\": [\n          \"ada@example.test\",\n        ],\n      },\n      {\n        \"name\": \"phone_number\",\n        \"values\": [\n          \"+15550100\",\n        ],\n      },\n      {\n        \"name\": \"what_are_you_interested_in\",\n        \"values\": [\n          \"Enterprise plan\",\n        ],\n      },\n    ],\n  };\n}\n\nfunction fakeLeadgen({ config, fake }: FakeRequest): unknown {\n  const boundLeadid = Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\");\n\n  return {\n    \"leadgen_id\": boundLeadid,\n    \"page_id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"form_id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"ad_id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"adgroup_id\": Array.from({ length: 15 }, () => fake.int(0, 9)).join(\"\"),\n    \"created_time\": 1787577300,\n  };\n}\n\nexport const facebookLeadAdsFaker: ConnectorFaker = (operation, request) => {\n  switch (operation) {\n    case \"lead_get\":\n      return fakeLeadGet(request);\n\n    case \"leadgen\":\n      return fakeLeadgen(request);\n\n    default:\n      // A faker asked for an operation it has no shape for must SAY so. Making\n      // something up would produce a green run whose output silently has none\n      // of the fields the author is about to reference.\n      throw new Error(\n        `facebook_lead_ads: no fake response is defined for \"${operation}\". ` +\n          \"Add a fixture under provider/fixtures/ and regenerate — a connector without a faker \" +\n          \"cannot be developed against, tested, or demonstrated.\",\n      );\n  }\n};\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/manifest.json by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/manifest.json (or weaver's template/) and regenerate:\n *\n *     npm run provider -- facebook_lead_ads\n */\n\n/**\n * Facebook Lead Ads, as one service descriptor shared by every Facebook Lead\n * Ads operation.\n *\n * @particle-academy/fancy-connector-core carries what is true of ALL\n * connectors. This carries what is true of Facebook Lead Ads: its base URL,\n * its auth scheme, its idempotency header, and its faker.\n *\n * ## The sandbox trap, written down where it is used\n *\n * Facebook Lead Ads has no sandbox. Meta's Lead Ads Testing Tool creates a\n * test lead on the REAL form, which fires the real webhook and appears\n * alongside real leads until somebody deletes it. Anything this reads is real\n * customer data belonging to a real advertiser.\n */\n\nimport type { ConnectorMode, PreparedRequest, ServiceDescriptor } from \"@particle-academy/fancy-connector-core\";\n\nimport { facebookLeadAdsFaker } from \"./faker.js\";\nimport { createHmac } from \"node:crypto\";\n\n/**\n * The connector API version this package was GENERATED against.\n *\n * A literal, never imported. An imported constant lets an upgrade rewrite the\n * very claim it exists to detect, after which the copy agrees with itself\n * forever.\n */\nexport const CONNECTOR_API_VERSION = 1;\n\nexport const FACEBOOK_LEAD_ADS_BASE_URLS = {\n  \"live\": \"https://graph.facebook.com/v25.0\"\n} as const;\n\n/** Credential keys a remote call cannot proceed without. */\nexport const FACEBOOK_LEAD_ADS_REQUIRES = [\n  \"pageAccessToken\",\n  \"appSecret\",\n  \"clientId\",\n  \"clientSecret\"\n] as const;\n\n/**\n * Apply Facebook Lead Ads's auth scheme to an outgoing request.\n *\n * Same as facebook-pages: Meta takes the token as a QUERY PARAMETER, and\n * appsecret_proof has to go in the query regardless, so both live in one place\n * and a request stays readable in a log.\n *\n * The mode is passed in because for some providers auth and estate are the\n * same decision expressed in the URL; here it is unused, and saying so is\n * cheaper than wondering later whether it was forgotten.\n */\nexport function facebookLeadAdsAuthorize(\n  credentials: Record<string, string | undefined>,\n  request: PreparedRequest,\n  _mode: ConnectorMode,\n): void {\n  const url = new URL(request.url);\n\n  url.searchParams.set(\"access_token\", String(credentials.pageAccessToken ?? \"\"));\n\n  const proof = createHmac(\"sha256\", String(credentials.appSecret ?? \"\"))\n    .update(String(credentials.pageAccessToken ?? \"\"))\n    .digest(\"hex\");\n\n  url.searchParams.set(\"appsecret_proof\", proof);\n  request.url = url.toString();\n}\n\n/** The Facebook Lead Ads service, for the TypeScript runtime. */\nexport const FACEBOOK_LEAD_ADS: ServiceDescriptor = {\n  service: \"facebook_lead_ads\",\n  title: \"Facebook Lead Ads\",\n  sandbox: \"none\",\n  baseUrls: { ...FACEBOOK_LEAD_ADS_BASE_URLS },\n  requires: [...FACEBOOK_LEAD_ADS_REQUIRES],\n  authorize: facebookLeadAdsAuthorize,\n  faker: facebookLeadAdsFaker,\n};\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/actions/lead-get.json by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/actions/lead-get.json (or weaver's template/) and regenerate:\n *\n *     npm run provider -- facebook_lead_ads\n */\n\n/**\n * Read one lead's answers by id. Pair this with the `leadgen` trigger, whose\n * delivery carries only the id.\n *\n * GET /{leadId} —\n * https://developers.facebook.com/docs/marketing-api/guides/lead-ads/retrieving\n *\n * Notice what is NOT here: no key, no base URL, no mode check, no retry loop,\n * no fake/real branch. This describes the request; callConnector resolves the\n * connection, picks the estate, and either calls Facebook Lead Ads or calls\n * the faker.\n */\n\nimport {\n  callConnector,\n  type ConnectorResult,\n  type RequestedMode,\n  type Transport,\n} from \"@particle-academy/fancy-connector-core\";\nimport { FACEBOOK_LEAD_ADS } from \"../service.js\";\n\nexport const LEAD_GET_OPERATION = \"lead_get\";\n\nexport type LeadGetOptions = {\n  /** The node's resolved config. Keys: leadId. */\n  config: Record<string, unknown>;\n  credentials?: Record<string, string | undefined>;\n  mode?: RequestedMode;\n  connectionId?: string | null;\n  input?: unknown;\n  attempts?: number;\n  /** Override the transport. The only way to exercise this without a network. */\n  transport?: Transport;\n};\n\nexport async function facebookLeadAdsLeadGet(options: LeadGetOptions): Promise<ConnectorResult> {\n  const config = options.config ?? {};\n\n  if (config.leadId === undefined || config.leadId === null || config.leadId === \"\") {\n    throw new Error(`lead_get: \"leadId\" is required (Lead ID).`);\n  }\n\n  return callConnector(FACEBOOK_LEAD_ADS, {\n    operation: LEAD_GET_OPERATION,\n    config,\n    input: options.input,\n    ...(options.credentials === undefined ? {} : { credentials: options.credentials }),\n    ...(options.mode === undefined ? {} : { mode: options.mode }),\n    ...(options.connectionId === undefined ? {} : { connectionId: options.connectionId }),\n    ...(options.attempts === undefined ? {} : { attempts: options.attempts }),\n    ...(options.transport === undefined ? {} : { transport: options.transport }),\n    request: {\n      method: \"GET\",\n      path: `/${encodeURIComponent(String(config.leadId))}`,\n      query: {},\n    },\n  });\n}\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/triggers/leadgen.json by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/triggers/leadgen.json (or weaver's template/) and regenerate:\n *\n *     npm run provider -- facebook_lead_ads\n */\n\n/**\n * Facebook Lead Ads's webhook trigger — the delivery contract.\n *\n * Kept beside the service descriptor rather than inside a node, because a\n * signature scheme is a fact about FACEBOOK LEAD ADS. Two Facebook Lead Ads\n * triggers must not be able to disagree about how a delivery is verified.\n */\n\nimport { verifyDelivery, type HmacScheme, type InboundDelivery, type TriggerDescriptor, type WebhookVerification } from \"@particle-academy/fancy-connector-core\";\nimport { facebookLeadAdsFaker } from \"../faker.js\";\n\nexport const FACEBOOK_LEAD_ADS_LEADGEN_SIGNATURE_HEADER = \"X-Hub-Signature-256\";\n\nexport const FACEBOOK_LEAD_ADS_LEADGEN_SCHEME: HmacScheme = {\n  algorithm: \"SHA-256\",\n  payload: (raw, timestamp) => raw,\n  encoding: \"hex\",\n};\n\n/** Strip the `sha256=` prefix the provider sends. */\nexport function parseFacebookLeadAdsSignature(raw: string): { signature?: string } {\n  return { signature: raw.startsWith(\"sha256=\") ? raw.slice(7) : raw };\n}\n\nexport const FACEBOOK_LEAD_ADS_LEADGEN: TriggerDescriptor = {\n  service: \"facebook_lead_ads\",\n  operation: \"leadgen\",\n  delivery: \"webhook\",\n  setup:\n    \"In the Meta app dashboard, add a Webhooks product, subscribe to the PAGE object and tick the `leadgen` field, and point the callback URL at the route your host mounts for this trigger. Meta first sends a GET carrying `hub.mode=subscribe`, `hub.verify_token` and `hub.challenge` -- the host must echo `hub.challenge` back as the body and check `hub.verify_token` against the value set in the dashboard, or the subscription is never activated. Then subscribe the app to each Page (`POST /{pageId}/subscribed_apps` with `subscribed_fields=leadgen`), which is a SEPARATE step: a webhook configured but not subscribed per Page delivers nothing and reports nothing.\",\n  verification: {\n    signatureHeader: FACEBOOK_LEAD_ADS_LEADGEN_SIGNATURE_HEADER,\n    scheme: FACEBOOK_LEAD_ADS_LEADGEN_SCHEME,\n    parse: parseFacebookLeadAdsSignature,\n  },\n  faker: facebookLeadAdsFaker,\n};\n\n/**\n * Verify one inbound Facebook Lead Ads delivery.\n *\n * The host calls this BEFORE starting a run, with the body exactly as\n * received. Re-serialised JSON changes key order and whitespace, and produces\n * a mismatch that looks precisely like a wrong secret — hours of debugging the\n * wrong thing.\n *\n * The secret is the connection's `appSecret`.\n */\nexport function verifyFacebookLeadAdsDelivery(\n  delivery: InboundDelivery,\n  appSecret: string | undefined,\n  now?: number,\n): Promise<WebhookVerification> {\n  return verifyDelivery(FACEBOOK_LEAD_ADS_LEADGEN, delivery, appSecret, now);\n}\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/actions/ + triggers/ by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/actions/ + triggers/ (or weaver's template/) and regenerate:\n *\n *     npm run provider -- facebook_lead_ads\n */\n\n/**\n * Facebook Lead Ads's node kinds with their TypeScript executors attached —\n * for hosts that EXECUTE on TS.\n *\n * The authoring surface in @particle-academy/facebook-lead-ads-ui carries no\n * executor: the editor is React on every host, so a PHP or Python project\n * installs the ui package and never this one.\n */\n\nimport type { NodeExecutor, NodeKindDefinition } from \"@particle-academy/fancy-flow/engine\";\nimport {\n  idempotencyKeyFor,\n  NO_IDEMPOTENCY_KEY_WARNING,\n  resolveConnection,\n  triggerEvent,\n  type RequestedMode,\n} from \"@particle-academy/fancy-connector-core\";\nimport { FACEBOOK_LEAD_ADS } from \"./service.js\";\n\nimport {\n  facebookLeadAdsLeadKind,\n  facebookLeadAdsWebhookTriggerKind,\n} from \"@particle-academy/facebook-lead-ads-ui\";\n\nimport { facebookLeadAdsLeadGet } from \"./actions/lead-get.js\";\nimport { FACEBOOK_LEAD_ADS_LEADGEN } from \"./triggers/leadgen.js\";\n\nexport const facebookLeadAdsLeadExecutor: NodeExecutor = async (ctx) => {\n  const config = ((ctx.node.data as { config?: Record<string, unknown> })?.config ?? {});\n\n  const result = await facebookLeadAdsLeadGet({\n    config,\n    input: ctx.inputs?.in,\n  });\n\n  ctx.emit({\n    type: \"log\",\n    level: \"info\",\n    nodeId: ctx.node.id,\n    message: `facebook_lead_ads lead_get ${(result.data as { id?: string })?.id} (${result.mode})`,\n  });\n\n  return { __port: \"out\", value: result };\n};\n\nexport const facebookLeadAdsWebhookTriggerExecutor: NodeExecutor = async (ctx) => {\n  const config = ((ctx.node.data as { config?: Record<string, unknown> })?.config ?? {});\n  const connection = resolveConnection({\n    service: FACEBOOK_LEAD_ADS.service,\n    operation: \"leadgen\",\n    sandbox: FACEBOOK_LEAD_ADS.sandbox,\n    baseUrls: FACEBOOK_LEAD_ADS.baseUrls,\n    requires: FACEBOOK_LEAD_ADS.requires,\n    connectionId: typeof config.connection === \"string\" ? config.connection : null,\n    requested: typeof config.mode === \"string\" ? (config.mode as RequestedMode) : null,\n  });\n\n  const event = triggerEvent(FACEBOOK_LEAD_ADS_LEADGEN, connection, ctx.inputs?.in, config);\n\n  return { __port: \"out\", value: event };\n};\n\n/** The kinds a TypeScript host registers. */\nexport const FACEBOOK_LEAD_ADS_RUNNABLE_KINDS: NodeKindDefinition[] = [\n  { ...facebookLeadAdsLeadKind, executor: facebookLeadAdsLeadExecutor },\n  { ...facebookLeadAdsWebhookTriggerKind, executor: facebookLeadAdsWebhookTriggerExecutor },\n];\n"]}

package/dist/flow.d.cts

@@ -0,0 +1,27 @@
+import { NodeKindDefinition, NodeExecutor } from '@particle-academy/fancy-flow/engine';
+
+/**
+ * GENERATED FILE — do not edit.
+ *
+ * Emitted from provider/actions/ + triggers/ by weaver's generator.
+ * A hand-edit here is destroyed by the next protocol sync, which is worse than
+ * being rejected, because it works until it silently does not. Fix
+ * provider/actions/ + triggers/ (or weaver's template/) and regenerate:
+ *
+ *     npm run provider -- facebook_lead_ads
+ */
+/**
+ * Facebook Lead Ads's node kinds with their TypeScript executors attached —
+ * for hosts that EXECUTE on TS.
+ *
+ * The authoring surface in @particle-academy/facebook-lead-ads-ui carries no
+ * executor: the editor is React on every host, so a PHP or Python project
+ * installs the ui package and never this one.
+ */
+
+declare const facebookLeadAdsLeadExecutor: NodeExecutor;
+declare const facebookLeadAdsWebhookTriggerExecutor: NodeExecutor;
+/** The kinds a TypeScript host registers. */
+declare const FACEBOOK_LEAD_ADS_RUNNABLE_KINDS: NodeKindDefinition[];
+
+export { FACEBOOK_LEAD_ADS_RUNNABLE_KINDS, facebookLeadAdsLeadExecutor, facebookLeadAdsWebhookTriggerExecutor };