@jskit-ai/connectors-catalog 0.1.1

package/test/hubspot.test.js

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { createConnectionService } from "../../connectors-core/src/server/index.js";
+import { createFileConnectionStore, createCredentialProtection } from "../../connectors-core/src/server/fileStorage.js";
+import { hubspotProvider } from "../src/server/hubspot.js";
+
+for (const perUser of [false, true]) test(`HubSpot OAuth ${perUser ? "per-user" : "shared rotating"} grants preserve protocol and ownership`, async (t) => {
+  const directory = await mkdtemp(path.join(tmpdir(), "hubspot-oauth-test-"));
+  t.after(() => rm(directory, { recursive: true, force: true }));
+  const callback = "https://example.test/integrations/hubspot/callback";
+  const context = { applicationId: "app", subjectId: "owner" };
+  const input = { context, integrationId: "hubspot" };
+  let time = Date.now(), exchanges = 0;
+  let tokenScope = "oauth crm.objects.contacts.read", apiStatus = 200;
+  const protection = createCredentialProtection({ keys: { current: new Uint8Array(32).fill(4) }, activeKeyId: "current" });
+  const options = {
+    configuration: { schemaVersion: 1, registrations: { hubspot: { source: "own", clientId: "client", clientSecretRef: "env:SECRET", callbackUrlRef: "env:CALLBACK", tokenEndpointAuthMethod: "client_secret_post" } }, integrations: {
+      hubspot: { provider: "hubspot", accountMode: perUser ? "per-user" : "shared", scopes: ["oauth", "crm.objects.contacts.read"], authentication: { method: "oauth2", registrationRef: "hubspot" } },
+      personal: { provider: "hubspot", accountMode: "shared", scopes: ["oauth", "crm.objects.contacts.read"], authentication: { method: "api-key", secretRef: "env:TOKEN" } }
+    } }, providers: [hubspotProvider], authorize: async owner => owner,
+    store: createFileConnectionStore({ directory, protection }), now: () => time,
+    resolveReference: async ref => ref === "env:CALLBACK" ? callback : ref === "env:TOKEN" ? "personal" : "secret",
+    fetchImpl: async (address, init) => {
+      const url = new URL(String(address)), headers = new Headers(init.headers);
+      if (url.pathname === "/oauth/2026-09/token") {
+        assert.equal(url.origin, "https://api.hubspot.com");
+        assert.equal(headers.get("accept"), "application/json");
+        const body = new URLSearchParams(init.body);
+        assert.equal(body.get("client_secret"), "secret");
+        if (body.get("grant_type") === "authorization_code") {
+          assert.equal(body.get("redirect_uri"), callback);
+          assert.equal(body.has("code_verifier"), false);
+        } else {
+          assert.equal(body.get("refresh_token"), `refresh-${exchanges}`);
+          assert.equal(body.has("redirect_uri"), false);
+        }
+        exchanges++;
+        return Response.json({ access_token: `access-${exchanges}`, refresh_token: `refresh-${exchanges}`, token_type: "Bearer", expires_in: 60, scopes: tokenScope.split(" ") });
+      }
+      assert.equal(url.origin, "https://api.hubapi.com");
+      assert.equal(url.pathname, "/crm/objects/2026-09/contacts");
+      assert.ok(headers.get("authorization") === `Bearer access-${exchanges}` || headers.get("authorization") === "Bearer personal");
+      if (apiStatus !== 200) return Response.json({ message: "private provider detail" }, { status: apiStatus });
+      return Response.json({ results: [{ id: "123" }] });
+    }
+  };
+  const service = createConnectionService(options);
+  for (const outcome of ["cancel", "denied"]) {
+    const attempt = new URL((await service.beginAuthorization(input)).authorizationUrl);
+    const denied = new URL(callback);
+    denied.searchParams.set("state", attempt.searchParams.get("state"));
+    if (outcome === "cancel") {
+      await service.cancelAuthorization({ ...input, state: attempt.searchParams.get("state") });
+      denied.searchParams.set("code", "unused");
+    } else denied.searchParams.set("error", "access_denied");
+    await assert.rejects(service.completeAuthorization({ ...input, callbackUrl: denied.href }), {
+      code: outcome === "cancel" ? "connector_attempt_invalid" : "connector_consent_denied"
+    });
+  }
+  assert.equal(exchanges, 0);
+  const { authorizationUrl } = await service.beginAuthorization(input);
+  const url = new URL(authorizationUrl);
+  assert.equal(url.origin + url.pathname, "https://app.hubspot.com/oauth/authorize");
+  assert.equal(url.searchParams.has("code_challenge_method"), false);
+  assert.equal(url.searchParams.get("scope"), "oauth crm.objects.contacts.read");
+  const returned = new URL(callback);
+  returned.searchParams.set("code", "code");
+  returned.searchParams.set("state", url.searchParams.get("state"));
+  assert.equal((await service.completeAuthorization({ ...input, callbackUrl: returned.href })).status, "connected");
+  await assert.rejects(service.completeAuthorization({ ...input, callbackUrl: returned.href }), { code: "connector_attempt_invalid" });
+  time += 40_000;
+  await Promise.all([service.invoke({ ...input, operation: "contacts.list" }), service.invoke({ ...input, operation: "contacts.list" })]);
+  assert.equal(exchanges, 2);
+  const restarted = createConnectionService({ ...options, store: createFileConnectionStore({ directory, protection }) });
+  time += 40_000;
+  await restarted.invoke({ ...input, operation: "contacts.list" });
+  assert.equal(exchanges, 3);
+  assert.equal((await restarted.connectApiKey({ context, integrationId: "personal" })).status, "connected");
+  const otherApp = { context: { ...context, applicationId: "another-app" }, integrationId: "hubspot" };
+  assert.equal((await restarted.status(otherApp)).status, "disconnected");
+  if (perUser) {
+    const otherUser = { context: { ...context, subjectId: "another-user" }, integrationId: "hubspot" };
+    assert.equal((await restarted.status(otherUser)).status, "disconnected");
+    await assert.rejects(restarted.invoke({ ...otherUser, operation: "contacts.list" }));
+    assert.equal((await restarted.status(input)).status, "connected");
+  }
+  tokenScope = "oauth";
+  time += 40_000;
+  await assert.rejects(restarted.invoke({ ...input, operation: "contacts.list" }), { code: "connector_scope_missing" });
+  await restarted.disconnect(input);
+  assert.equal((await restarted.status(input)).status, "disconnected");
+});
+
+test("HubSpot rejects malformed permission grants and preserves OAuth errors", async () => {
+  for (const scopes of [undefined, "oauth", [42], ["bad scope"]]) {
+    await assert.rejects(hubspotProvider.normalizeTokenResponse(Response.json({ access_token: "secret", scopes })), { code: "connector_response_invalid" });
+  }
+  const failure = Response.json({ error: "invalid_grant" }, { status: 400 });
+  assert.equal(await hubspotProvider.normalizeTokenResponse(failure), failure);
+});

package/test/inngest.test.js

@@ -0,0 +1,219 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import { createConnectionService } from "../../connectors-core/src/server/index.js";
+import { createFileConnectionStore, createCredentialProtection } from "../../connectors-core/src/server/fileStorage.js";
+import { parseIntegrationConfiguration } from "../../connectors-core/src/shared/configuration.js";
+import { inngestProvider } from "../src/server/inngest.js";
+
+const context = { applicationId: "workflow-app", subjectId: "workspace" };
+const input = { context, integrationId: "jobs" };
+const event = { name: "app/report.requested", data: { reportId: "42", filters: ["active"] }, id: "report-requested-42", ts: 1788920000000 };
+const appPage = { data: [{ id: "reports", name: "Reports", method: "SERVE", isArchived: false }], page: { cursor: null, hasMore: false, limit: 20 } };
+
+async function fixture(t) {
+  const directory = await mkdtemp(path.join(tmpdir(), "inngest-connectors-"));
+  t.after(() => rm(directory, { recursive: true, force: true }));
+  const protection = createCredentialProtection({ keys: { current: new Uint8Array(32).fill(8) }, activeKeyId: "current" });
+  const requests = [];
+  const resolved = [];
+  const state = { signing: "signkey-prod-fixture-signing", eventKey: "event+key/with?special#chars=", httpStatus: 200,
+    page: appPage, receipt: { ids: ["01K1QQ3VQ8R3M8QX4D51J8G7XH"], status: 200 } };
+  const options = {
+    configuration: { schemaVersion: 1, registrations: {}, integrations: { jobs: {
+      provider: "inngest", accountMode: "shared", scopes: [], authentication: { method: "api-key", secretRef: "env:INNGEST_SIGNING_KEY" },
+      settings: { eventKeyRef: "env:INNGEST_EVENT_KEY", branchEnvironment: "feature/my-branch" }
+    } }, extensions: { preserve: true } },
+    providers: [inngestProvider], store: createFileConnectionStore({ directory, protection }),
+    authorize: async (owner, request) => {
+      if (request.operation === "events.send" && request.input.name !== event.name) return null;
+      return owner;
+    },
+    resolveReference: async (reference) => {
+      resolved.push(reference);
+      if (reference === "env:INNGEST_SIGNING_KEY") return state.signing;
+      if (reference === "env:INNGEST_EVENT_KEY") return state.eventKey;
+      throw new Error("Unrecognized binding.");
+    },
+    fetchImpl: async (address, init) => {
+      init.signal.throwIfAborted();
+      const url = new URL(String(address));
+      requests.push({ url, init, headers: new Headers(init.headers), body: init.body && JSON.parse(init.body) });
+      if (state.pause) {
+        state.started?.();
+        return new Promise((resolve, reject) => init.signal.addEventListener("abort", () => reject(init.signal.reason), { once: true }));
+      }
+      return Response.json(state.httpStatus === 200 ? (url.hostname === "inn.gs" ? state.receipt : state.page) : { error: state.eventKey, signing: state.signing },
+        { status: state.httpStatus, headers: { Location: "https://unexpected.example", Link: '<https://unexpected.example/next>; rel="next"' } });
+    }
+  };
+  return { service: createConnectionService(options), options, directory, protection, state, requests, resolved };
+}
+
+test("Inngest verifies only signing-key metadata and keeps both credential values out of file state", async (t) => {
+  const { service, options, directory, protection, requests, resolved, state } = await fixture(t);
+  const connection = await service.connectApiKey(input);
+  assert.equal(connection.status, "connected");
+  assert.deepEqual(resolved, ["env:INNGEST_SIGNING_KEY"]);
+  assert.equal(requests.length, 1);
+  assert.equal(requests[0].url.href, "https://api.inngest.com/v2/apps?limit=20&archived=false");
+  assert.equal(requests[0].init.method, "GET");
+  assert.equal(requests[0].headers.get("authorization"), `Bearer ${state.signing}`);
+  assert.equal(requests[0].headers.get("x-inngest-env"), null, "Event branch selection does not silently retarget API reads.");
+  for (const name of await readdir(directory)) {
+    const text = await readFile(path.join(directory, name), "utf8");
+    assert.equal(text.includes(state.eventKey), false);
+    assert.equal(text.includes(state.signing), false);
+  }
+  const restarted = createConnectionService({ ...options, store: createFileConnectionStore({ directory, protection }) });
+  assert.deepEqual(await restarted.status(input), connection);
+  for (const owner of [{ ...context, applicationId: "different-app" }, { ...context, subjectId: "different-owner" }]) {
+    await assert.rejects(restarted.invoke({ ...input, context: owner, operation: "events.send", input: event }), { code: "connector_reconnect_required" });
+  }
+  assert.equal(requests.length, 1);
+  await restarted.disconnect(input);
+  assert.equal((await service.status(input)).status, "disconnected");
+});
+
+test("Inngest event delivery uses only the encoded Event Key and preserves payload and branch", async (t) => {
+  const { service, requests, state } = await fixture(t);
+  await service.connectApiKey(input);
+  const original = structuredClone(event);
+  assert.deepEqual(await service.invoke({ ...input, operation: "events.send", input: event }), state.receipt);
+  const request = requests.at(-1);
+  assert.equal(request.url.href, `https://inn.gs/e/${encodeURIComponent(state.eventKey)}`);
+  assert.equal(request.url.origin, "https://inn.gs");
+  assert.equal(request.url.search, "");
+  assert.equal(request.url.hash, "");
+  assert.equal(request.headers.get("authorization"), null);
+  assert.equal(request.headers.get("x-inngest-env"), "feature/my-branch");
+  assert.equal(request.init.redirect, "error");
+  assert.deepEqual(request.body, event);
+  assert.equal(JSON.stringify(request.body).includes("env:"), false);
+  assert.deepEqual(event, original);
+  state.eventKey = "rotated-event-key";
+  await service.invoke({ ...input, operation: "events.send", input: event });
+  assert.equal(requests.at(-1).url.pathname, "/e/rotated-event-key");
+  state.signing = "signkey-prod-rotated";
+  await service.invoke({ ...input, operation: "apps.list" });
+  assert.equal(requests.at(-1).headers.get("authorization"), `Bearer ${state.signing}`);
+});
+
+test("Inngest exposes bounded metadata pages without following provider links", async (t) => {
+  const { service, requests, state } = await fixture(t);
+  await service.connectApiKey(input);
+  state.page = { data: [{ id: "send-report", triggers: [{ type: "EVENT", value: event.name }] }], page: { cursor: "next+/=cursor", hasMore: true, limit: 5 } };
+  assert.deepEqual(await service.invoke({ ...input, operation: "functions.list", input: { appId: "reports/a?b", limit: 5, cursor: "opaque+/=" } }), state.page);
+  assert.equal(requests.at(-1).url.pathname, "/v2/apps/reports%2Fa%3Fb/functions");
+  assert.equal(requests.at(-1).url.searchParams.get("cursor"), "opaque+/=");
+  await service.invoke({ ...input, operation: "apps.list", input: { archived: true, limit: 100 } });
+  assert.equal(requests.at(-1).url.searchParams.get("archived"), "true");
+  assert.equal(requests.length, 3);
+});
+
+test("Inngest rejects invalid configuration, event payloads and metadata inputs before HTTP", async (t) => {
+  const { options, service, requests } = await fixture(t);
+  const parse = (config) => parseIntegrationConfiguration(JSON.stringify(config), { providers: [inngestProvider] });
+  assert.deepEqual(parse(options.configuration), options.configuration);
+  for (const eventKeyRef of [undefined, "raw-key", "env: KEY"]) {
+    const config = structuredClone(options.configuration);
+    config.integrations.jobs.settings.eventKeyRef = eventKeyRef;
+    assert.throws(() => parse(config));
+  }
+  for (const branchEnvironment of ["branch\nAuthorization: other", "branch with spaces", "bránch"]) {
+    const config = structuredClone(options.configuration);
+    config.integrations.jobs.settings.branchEnvironment = branchEnvironment;
+    assert.throws(() => parse(config));
+  }
+  await service.connectApiKey(input);
+  const count = requests.length;
+  for (const invalid of [{ name: event.name }, { name: event.name, data: [] }, { ...event, ts: 1 }, { ...event, ts: 1788920000000.5 }, { ...event, url: "https://unexpected.example" }]) {
+    await assert.rejects(service.invoke({ ...input, operation: "events.send", input: invalid }), { code: "connector_input_invalid" });
+  }
+  for (const value of [0, 101, 3.5]) await assert.rejects(service.invoke({ ...input, operation: "apps.list", input: { limit: value } }), { code: "connector_input_invalid" });
+  for (const appId of [".", "..", ""]) await assert.rejects(service.invoke({ ...input, operation: "functions.list", input: { appId } }), { code: "connector_input_invalid" });
+  assert.equal(requests.length, count);
+});
+
+test("Inngest authorizes event name and data before delivery and checks the Event Key binding lazily", async (t) => {
+  const { service, requests, state, resolved } = await fixture(t);
+  await service.connectApiKey(input);
+  const count = requests.length;
+  await assert.rejects(service.invoke({ ...input, operation: "events.send", input: { ...event, name: "unauthorized/event" } }), { code: "connector_access_denied" });
+  assert.equal(resolved.includes("env:INNGEST_EVENT_KEY"), false);
+  for (const key of [undefined, "", "\n", "key\rAuthorization: secret"]) {
+    state.eventKey = key;
+    await assert.rejects(service.invoke({ ...input, operation: "events.send", input: event }), { code: "connector_binding_missing" });
+  }
+  assert.equal(requests.length, count);
+  assert.equal((await service.status(input)).status, "connected", "The existing metadata grant remains; Event Key validity was not asserted.");
+});
+
+test("Inngest rejects ambiguous event receipts and provider failures without disclosing credentials or retrying", async (t) => {
+  const { service, state, requests } = await fixture(t);
+  await service.connectApiKey(input);
+  for (const [receipt, code] of [[{ status: 200, ids: [] }, "connector_response_invalid"], [{ status: 200, ids: ["id"], error: "failure" }, "connector_response_invalid"],
+    [{ status: 403, error: "denied" }, "connector_permission_denied"], [{ status: 429, error: "limited" }, "connector_rate_limited"]]) {
+    state.receipt = receipt;
+    const count = requests.length;
+    await assert.rejects(service.invoke({ ...input, operation: "events.send", input: event }), { code });
+    assert.equal(requests.length, count + 1);
+  }
+  for (const [status, code] of [[403, "connector_permission_denied"], [429, "connector_rate_limited"], [500, "connector_provider_failed"]]) {
+    state.httpStatus = status;
+    await assert.rejects(service.invoke({ ...input, operation: "events.send", input: event }), (error) => error.code === code && !error.message.includes(state.eventKey) && !error.message.includes(state.signing));
+  }
+  state.httpStatus = 401;
+  await assert.rejects(service.invoke({ ...input, operation: "events.send", input: event }), { code: "connector_reconnect_required" });
+  assert.equal((await service.status(input)).status, "reconnect-required");
+});
+
+test("Inngest rejects malformed metadata and failed verification without creating a connection", async (t) => {
+  const { service, state } = await fixture(t);
+  for (const page of [{ ok: true }, { data: [{}], page: { hasMore: false, limit: 20 } }, { data: [], page: { hasMore: "false", limit: 20 } }]) {
+    state.page = page;
+    await assert.rejects(service.connectApiKey(input), { code: "connector_response_invalid" });
+    assert.equal((await service.status(input)).status, "disconnected");
+  }
+  state.httpStatus = 401;
+  await assert.rejects(service.connectApiKey(input), { code: "connector_reconnect_required" });
+  assert.equal((await service.status(input)).status, "disconnected");
+});
+
+test("Inngest reference and branch changes require reverification, including branch removal", async (t) => {
+  const { service, options, requests } = await fixture(t);
+  await service.connectApiKey(input);
+  for (const changes of [{ eventKeyRef: "env:OTHER_EVENT_KEY" }, { branchEnvironment: "other-branch" }, { branchEnvironment: undefined }]) {
+    const config = structuredClone(options.configuration);
+    Object.assign(config.integrations.jobs.settings, changes);
+    for (const [name, value] of Object.entries(changes)) if (value === undefined) delete config.integrations.jobs.settings[name];
+    const changed = createConnectionService({ ...options, configuration: config });
+    const count = requests.length;
+    assert.equal((await changed.status(input)).status, "reconnect-required");
+    await assert.rejects(changed.invoke({ ...input, operation: "events.send", input: event }), { code: "connector_reconnect_required" });
+    assert.equal(requests.length, count);
+  }
+  const config = structuredClone(options.configuration);
+  delete config.integrations.jobs.settings.branchEnvironment;
+  const changed = createConnectionService({ ...options, configuration: config });
+  await changed.connectApiKey(input);
+  await changed.invoke({ ...input, operation: "events.send", input: event });
+  assert.equal(requests.at(-1).headers.get("x-inngest-env"), null);
+});
+
+test("Inngest cancellation reports interruption without replaying an event", async (t) => {
+  const { service, state, requests } = await fixture(t);
+  await service.connectApiKey(input);
+  const controller = new AbortController();
+  state.pause = true;
+  const started = new Promise((resolve) => { state.started = resolve; });
+  const pending = service.invoke({ ...input, operation: "events.send", input: event, signal: controller.signal });
+  const rejected = assert.rejects(pending, { code: "connector_cancelled" });
+  await started;
+  controller.abort();
+  await rejected;
+  assert.equal(requests.length, 2);
+  assert.equal((await service.status(input)).status, "connected");
+});

package/test/lightspeed.test.js

@@ -0,0 +1,250 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { createConnectionService } from "../../connectors-core/src/server/index.js";
+import { createFileConnectionStore, createCredentialProtection } from "../../connectors-core/src/server/fileStorage.js";
+import { parseIntegrationConfiguration } from "../../connectors-core/src/shared/configuration.js";
+import { lightspeedProvider } from "../src/server/lightspeed.js";
+
+const context = { applicationId: "application-one", subjectId: "user-one" };
+const args = { context, integrationId: "retail" };
+const scopes = ["products:read", "customers:read", "outlets:read"];
+const callback = "https://app.example.test/oauth/lightspeed/callback";
+const item = { id: "06bf537b-c783-11e6-f6b9-53a81bd6b215", version: 1690497245, name: null, first_name: null };
+const page = { data: [item], version: { min: item.version, max: item.version } };
+
+async function fixture(t, domainPrefix = "fixture-store", selectedScopes = scopes) {
+  const directory = await mkdtemp(path.join(tmpdir(), "lightspeed-connector-"));
+  t.after(() => rm(directory, { recursive: true, force: true }));
+  const api = `https://${domainPrefix}.retail.lightspeed.app`;
+  const state = { time: Date.now(), count: 0, status: 200, value: undefined, tokenStatus: 200, tokenPatch: {}, hang: false };
+  const requests = [];
+  const configuration = { schemaVersion: 1, registrations: { lightspeed: { source: "own", clientId: "fixture-lightspeed-client", clientSecretRef: "env:LIGHTSPEED_SECRET", callbackUrlRef: "env:LIGHTSPEED_CALLBACK" } },
+    integrations: { retail: { provider: "lightspeed", accountMode: "per-user", settings: { domainPrefix }, scopes: selectedScopes, authentication: { method: "oauth2", registrationRef: "lightspeed" } } } };
+  const options = {
+    configuration, providers: [{ ...lightspeedProvider, requestTimeoutMs: 50 }], authorize: async (owner) => owner,
+    now: () => state.time, resolveReference: async (ref) => ({ "env:LIGHTSPEED_SECRET": "fixture-client-secret", "env:LIGHTSPEED_CALLBACK": callback })[ref],
+    store: createFileConnectionStore({ directory, protection: createCredentialProtection({ keys: { current: new Uint8Array(32).fill(5) }, activeKeyId: "current" }) }),
+    fetchImpl: async (address, init) => {
+      const url = new URL(String(address)); requests.push({ url, init });
+      assert.equal(url.origin, api);
+      if (url.pathname === "/api/1.0/token") {
+        assert.equal(init.method, "POST");
+        assert.match(new Headers(init.headers).get("content-type"), /application\/x-www-form-urlencoded/u);
+        const body = new URLSearchParams(init.body);
+        assert.equal(body.get("client_id"), "fixture-lightspeed-client"); assert.equal(body.get("client_secret"), "fixture-client-secret");
+        if (body.get("grant_type") === "authorization_code") { assert.equal(body.get("redirect_uri"), callback); assert.equal(body.get("code"), "fixture-code"); }
+        else { assert.equal(body.get("grant_type"), "refresh_token"); assert.equal(body.get("refresh_token"), `fixture-refresh-${state.count}`); }
+        state.count += 1;
+        return Response.json(state.tokenStatus === 200 ? { access_token: `fixture-access-${state.count}`, refresh_token: `fixture-refresh-${state.count}`,
+          token_type: "Bearer", expires_in: 60, expires: Math.floor(state.time / 1000) + 60, domain_prefix: domainPrefix, scope: selectedScopes.join(" "), ...state.tokenPatch }
+          : { error: "invalid_grant", error_description: "private provider details" }, { status: state.tokenStatus });
+      }
+      assert.match(url.pathname, /^\/api\/2026-07\/(products|customers|outlets|sales|inventory)$/u);
+      assert.equal(init.method, url.pathname.endsWith("/inventory") ? "POST" : "GET"); assert.equal(init.redirect, "error");
+      assert.equal(new Headers(init.headers).get("authorization"), `Bearer fixture-access-${state.count}`);
+      assert.equal(url.searchParams.has("access_token"), false);
+      if (state.hang) return new Promise((_, reject) => {
+        const timer = setTimeout(() => reject(new Error("Missing abort")), 1000);
+        const abort = () => { clearTimeout(timer); reject(init.signal.reason); };
+        if (init.signal.aborted) abort(); else init.signal.addEventListener("abort", abort, { once: true });
+      });
+      if (state.status === 204) return new Response(null, { status: 204 });
+      if (typeof state.value === "string") return new Response(state.value, { status: state.status });
+      return Response.json(state.value === undefined ? page : state.value, { status: state.status });
+    }
+  };
+  const service = createConnectionService(options);
+  const start = async () => {
+    const { authorizationUrl } = await service.beginAuthorization({ ...args, verificationInput: { page_size: 1 } }); const url = new URL(authorizationUrl);
+    const redirect = new URL(callback); redirect.searchParams.set("code", "fixture-code"); redirect.searchParams.set("state", url.searchParams.get("state"));
+    redirect.searchParams.set("domain_prefix", domainPrefix); redirect.searchParams.set("scope", selectedScopes.join(" "));
+    return { url, callbackUrl: redirect.href };
+  };
+  const connect = async () => service.completeAuthorization({ ...args, callbackUrl: (await start()).callbackUrl });
+  return { directory, service, options, state, requests, start, connect, api };
+}
+
+test("Lightspeed uses central code consent, a configured store token endpoint and encrypted restartable files", async (t) => {
+  const f = await fixture(t); const started = await f.start();
+  assert.equal(started.url.href.split("?")[0], "https://secure.retail.lightspeed.app/connect");
+  assert.equal(started.url.searchParams.get("scope"), scopes.join(" "));
+  assert.equal(started.url.searchParams.get("redirect_uri"), callback);
+  assert.equal(started.url.searchParams.get("code_challenge_method"), "S256"); assert.equal(started.url.searchParams.has("client_secret"), false);
+  await f.service.completeAuthorization({ ...args, callbackUrl: started.callbackUrl });
+  assert.ok(new URLSearchParams(f.requests[0].init.body).get("code_verifier"));
+  assert.equal(f.requests[1].url.search, "?page_size=1&deleted=false");
+  for (const file of await readdir(f.directory)) {
+    const text = await readFile(path.join(f.directory, file), "utf8");
+    for (const secret of ["fixture-code", "fixture-client-secret", "fixture-access-1", "fixture-refresh-1"]) assert.equal(text.includes(secret), false);
+  }
+  const restarted = createConnectionService(f.options);
+  assert.equal((await restarted.status(args)).status, "connected");
+  assert.deepEqual(await restarted.invoke({ ...args, operation: "products.list" }), page);
+});
+
+test("Lightspeed reads version pages, empty collections and nullable customer fields without traversing automatically", async (t) => {
+  const f = await fixture(t); await f.connect();
+  for (const operation of ["products.list", "customers.list", "outlets.list"]) {
+    const before = f.requests.length;
+    assert.deepEqual(await f.service.invoke({ ...args, operation, input: { page_size: 2, after: 100, before: 2000000000, deleted: true } }), page);
+    assert.equal(f.requests.length, before + 1); assert.equal(f.requests.at(-1).url.search, "?after=100&before=2000000000&page_size=2&deleted=true");
+    f.state.value = { data: [], version: { min: null, max: null } };
+    assert.deepEqual(await f.service.invoke({ ...args, operation }), f.state.value);
+    f.state.value = undefined;
+  }
+  f.state.value = { data: [{ ...item, first_name: null, last_name: null }] };
+  assert.deepEqual(await f.service.invoke({ ...args, operation: "customers.list" }), f.state.value);
+  f.state.value = { data: [] }; assert.deepEqual(await f.service.invoke({ ...args, operation: "customers.list" }), { data: [] });
+});
+
+test("Lightspeed rejects invalid version bounds, unsupported searches, arbitrary URLs and writes before transport", async (t) => {
+  const f = await fixture(t); await f.connect(); const before = f.requests.length;
+  for (const input of [{ after: -1 }, { after: 1.5 }, { after: Number.MAX_SAFE_INTEGER + 1 }, { before: -1 }, { before: 2.5 },
+    { after: 10, before: 10 }, { after: 11, before: 10 }, { page_size: 101 }, { page_size: 0 }, { page_size: 1.5 }, { deleted: "wrong" },
+    { url: "https://other.test" }, { domain_prefix: "other-store" }, { sku: "fixture" }, { name: "fixture" }]) {
+    await assert.rejects(f.service.invoke({ ...args, operation: "products.list", input }), { code: "connector_input_invalid" });
+  }
+  await assert.rejects(f.service.invoke({ ...args, operation: "products.create" }), { code: "connector_operation_unknown" });
+  assert.equal(f.requests.length, before);
+});
+
+test("Lightspeed uses actual granted scopes and host ownership before any store read", async (t) => {
+  const f = await fixture(t); f.state.tokenPatch.scope = "products:read"; await f.connect();
+  assert.deepEqual((await f.service.status(args)).grantedScopes, ["products:read"]);
+  await assert.rejects(f.service.invoke({ ...args, operation: "customers.list" }), { code: "connector_scope_missing" });
+  for (const owner of [{ ...context, applicationId: "other" }, { ...context, subjectId: "other" }]) {
+    await assert.rejects(f.service.invoke({ ...args, context: owner, operation: "products.list" }), { code: "connector_reconnect_required" });
+  }
+  const denied = createConnectionService({ ...f.options, authorize: async () => null });
+  await assert.rejects(denied.invoke({ ...args, operation: "products.list" }), { code: "connector_access_denied" });
+  assert.equal(f.requests.length, 2);
+  const reduced = await fixture(t); reduced.state.tokenPatch.scope = "customers:read";
+  await assert.rejects(reduced.connect(), { code: "connector_scope_missing" });
+  assert.equal((await reduced.service.status(args)).status, "disconnected"); assert.equal(reduced.requests.length, 1);
+});
+
+test("Lightspeed persists every rotated refresh token even if the subsequent API read fails", async (t) => {
+  const f = await fixture(t); await f.connect(); f.state.time += 40_000;
+  await Promise.all([f.service.invoke({ ...args, operation: "products.list" }), f.service.invoke({ ...args, operation: "products.list" })]);
+  assert.equal(f.state.count, 2);
+  f.state.time += 40_000; f.state.status = 429;
+  await assert.rejects(f.service.invoke({ ...args, operation: "products.list" }), { code: "connector_rate_limited" });
+  f.state.status = 200;
+  const restarted = createConnectionService(f.options); await restarted.invoke({ ...args, operation: "products.list" });
+  assert.equal(f.state.count, 3); assert.deepEqual((await restarted.status(args)).grantedScopes, scopes);
+  f.state.time += 40_000; await restarted.invoke({ ...args, operation: "customers.list" }); assert.equal(f.state.count, 4);
+});
+
+test("Lightspeed rejects mismatched store grants and never follows callback-supplied destinations", async (t) => {
+  for (const prefix of [undefined, "other-store", "fixture-store.attacker.test", "https://fixture-store.retail.lightspeed.app"]) {
+    const f = await fixture(t); f.state.tokenPatch.domain_prefix = prefix;
+    const start = await f.start(); const redirect = new URL(start.callbackUrl); redirect.searchParams.set("domain_prefix", "attacker.test");
+    await assert.rejects(f.service.completeAuthorization({ ...args, callbackUrl: redirect.href }), { code: "connector_response_invalid" });
+    assert.equal(f.requests.length, 1); assert.equal(f.requests[0].url.origin, f.api);
+  }
+});
+
+test("Lightspeed requires scopes, expiry and replacement refresh tokens from successful token responses", async (t) => {
+  for (const patch of [{ scope: undefined }, { scope: "" }, { scope: "products:read\ncustomers:read" }, { expires_in: undefined },
+    { expires_in: 0 }, { expires_in: 1.5 }, { refresh_token: undefined }, { refresh_token: "" }]) {
+    const f = await fixture(t); f.state.tokenPatch = patch;
+    await assert.rejects(f.connect(), { code: "connector_response_invalid" }); assert.equal(f.requests.length, 1);
+  }
+  const f = await fixture(t); await f.connect(); f.state.time += 40_000; f.state.tokenPatch.refresh_token = undefined;
+  await assert.rejects(f.service.invoke({ ...args, operation: "products.list" }), { code: "connector_response_invalid" });
+  assert.equal(f.requests.length, 3);
+});
+
+test("Lightspeed configuration changes invalidate grants and denied, cancelled or replayed consent preserves saved access", async (t) => {
+  const f = await fixture(t); await f.connect();
+  const configuration = structuredClone(f.options.configuration); configuration.integrations.retail.settings.domainPrefix = "other-store";
+  await assert.rejects(createConnectionService({ ...f.options, configuration }).invoke({ ...args, operation: "products.list" }), { code: "connector_reconnect_required" });
+  const start = await f.start(); const denied = new URL(start.callbackUrl); denied.searchParams.delete("code"); denied.searchParams.set("error", "access_denied");
+  await assert.rejects(f.service.completeAuthorization({ ...args, callbackUrl: denied.href }), { code: "connector_consent_denied" });
+  await assert.rejects(f.service.completeAuthorization({ ...args, callbackUrl: start.callbackUrl }), { code: "connector_attempt_invalid" });
+  const pending = await f.start(); await f.service.cancelAuthorization({ ...args, state: pending.url.searchParams.get("state") });
+  await assert.rejects(f.service.completeAuthorization({ ...args, callbackUrl: pending.callbackUrl }), { code: "connector_attempt_invalid" });
+  assert.equal((await f.service.status(args)).status, "connected");
+  await f.service.disconnect(args); assert.equal((await f.service.status(args)).status, "disconnected");
+  assert.equal(f.requests.length, 2);
+});
+
+test("Lightspeed rejects malformed successes and oversized pages and redacts provider failures", async (t) => {
+  const f = await fixture(t); await f.connect();
+  for (const [status, code] of [[403, "connector_permission_denied"], [500, "connector_provider_failed"], [429, "connector_rate_limited"]]) {
+    f.state.status = status; f.state.value = { message: "private provider details" };
+    await assert.rejects(f.service.invoke({ ...args, operation: "products.list" }), (error) => error.code === code && !error.message.includes("private"));
+  }
+  f.state.status = 200;
+  for (const value of [null, "invalid json", {}, { data: [] }, { data: [{ ...item, version: Number.MAX_SAFE_INTEGER + 1 }], version: page.version },
+    { data: [{ ...item, id: null }], version: page.version }, { data: [], version: { min: 0, max: null } },
+    { data: [item], version: { min: item.version + 1, max: item.version } }, { data: [item, item], version: page.version }]) {
+    f.state.value = value;
+    await assert.rejects(f.service.invoke({ ...args, operation: "products.list", input: { page_size: 1 } }), (error) => ["connector_response_invalid", "connector_provider_failed"].includes(error.code));
+  }
+  f.state.value = undefined; f.state.status = 204;
+  await assert.rejects(f.service.invoke({ ...args, operation: "products.list" }), { code: "connector_response_invalid" });
+  f.state.status = 401;
+  await assert.rejects(f.service.invoke({ ...args, operation: "products.list" }), { code: "connector_reconnect_required" });
+});
+
+test("Lightspeed invalid refresh tokens require reconnect without returning provider text", async (t) => {
+  const f = await fixture(t); await f.connect(); f.state.time += 40_000; f.state.tokenStatus = 400;
+  await assert.rejects(f.service.invoke({ ...args, operation: "products.list" }), (error) => error.code === "connector_reconnect_required" && !error.message.includes("private"));
+  assert.equal((await f.service.status(args)).status, "reconnect-required"); assert.equal(f.requests.length, 3);
+});
+
+test("Lightspeed delivers cancellation and timeout without retry", async (t) => {
+  const f = await fixture(t); await f.connect(); f.state.hang = true;
+  const abort = new AbortController(); const result = f.service.invoke({ ...args, operation: "customers.list", signal: abort.signal });
+  setTimeout(() => abort.abort(), 10); await assert.rejects(result, { code: "connector_cancelled" });
+  await assert.rejects(f.service.invoke({ ...args, operation: "customers.list" }), { code: "connector_provider_timeout" });
+  assert.equal(f.requests.length, 4);
+});
+
+test("Lightspeed guide and form share strict store/reference validation and all 49 permissions", async () => {
+  const guide = await readFile(new URL("../docs/lightspeed.md", import.meta.url), "utf8");
+  const json = guide.match(/```json\n([\s\S]*?)\n```/u)[1];
+  const configuration = parseIntegrationConfiguration(json, { providers: [lightspeedProvider] });
+  assert.equal(configuration.integrations.retail.settings.domainPrefix, "your-store");
+  assert.equal(lightspeedProvider.scopes.length, 49); assert.equal(lightspeedProvider.scopes.filter((scope) => scope.recommended).length, 16);
+  for (const value of ["", "https://your-store.retail.lightspeed.app", "a.b", "a b", "a/b", "a@b", "a?b", "-a", "a-", "STORE", "a".repeat(64)]) {
+    const invalid = JSON.parse(json); invalid.integrations.retail.settings.domainPrefix = value;
+    assert.throws(() => parseIntegrationConfiguration(JSON.stringify(invalid), { providers: [lightspeedProvider] }));
+  }
+  for (const [field, value] of [["clientSecretRef", "raw-secret"], ["callbackUrlRef", callback]]) {
+    const invalid = JSON.parse(json); invalid.registrations.lightspeed[field] = value;
+    assert.throws(() => parseIntegrationConfiguration(JSON.stringify(invalid), { providers: [lightspeedProvider] }));
+  }
+});
+
+
+test("Lightspeed inventory and sales preserve quantities, paging and permission boundaries", async t => {
+  const f = await fixture(t, "fixture-store", [...scopes, "inventory:read", "sales:read"]); await f.connect();
+  f.state.value = [{ product_id: item.id, outlet_id: "outlet-1", version: 100, current_inventory_level: "4.000", quantity_to_procure: "2.000" }];
+  assert.deepEqual(await f.service.invoke({ ...args, operation: "inventory.list", input: { size: 2, product_id: item.id, variants: true } }), f.state.value);
+  assert.deepEqual(JSON.parse(f.requests.at(-1).init.body), { size: 2, include_deleted: false, sort_direction: "asc", product_id: item.id, variants: true });
+  await f.service.invoke({ ...args, operation: "inventory.list", input: { after: 100, size: 2 } });
+  assert.equal(JSON.parse(f.requests.at(-1).init.body).after, 100);
+  f.state.value = [];
+  assert.deepEqual(await f.service.invoke({ ...args, operation: "inventory.list" }), []);
+  f.state.value = { data: [{ ...item, customer_id: "customer-1", total_price: "42.50" }], version: page.version };
+  assert.deepEqual(await f.service.invoke({ ...args, operation: "sales.list", input: { page_size: 2 } }), f.state.value);
+  assert.equal(f.requests.at(-1).url.search, "?page_size=2");
+  const before = f.requests.length;
+  for (const invalid of [{ variants: true }, { after: 2, before: 1 }, { size: 1001 }, { product_id: "../other" }])
+    await assert.rejects(f.service.invoke({ ...args, operation: "inventory.list", input: invalid }), { code: "connector_input_invalid" });
+  const denied = createConnectionService({ ...f.options, authorize: async (owner, request) => request.operation === "sales.list" ? null : owner });
+  await assert.rejects(denied.invoke({ ...args, operation: "sales.list" }), { code: "connector_access_denied" });
+  assert.equal(f.requests.length, before);
+  for (const malformed of [{ data: [] }, [{ version: "unknown" }], [{ version: 1 }, { version: 2 }]]) {
+    f.state.value = malformed;
+    await assert.rejects(f.service.invoke({ ...args, operation: "inventory.list", input: { size: 1 } }), { code: "connector_response_invalid" });
+  }
+  const limited = await fixture(t); await limited.connect(); const count = limited.requests.length;
+  await assert.rejects(limited.service.invoke({ ...args, operation: "inventory.list" }), { code: "connector_scope_missing" });
+  assert.equal(limited.requests.length, count);
+});