@shopimind/integration-kit-js 1.0.0

package/dist/testing/harness.d.ts

@@ -0,0 +1,49 @@
+import { type SpmHttpClient } from '@shopimind/sdk-js';
+import { type IntegrationApp } from '../runtime/create-app.js';
+import type { Integration } from '../integration/types.js';
+export interface TestAppOptions {
+    /** Simulated SDK client (default: an offline stub returning empty ok responses). */
+    spm?: SpmHttpClient;
+    secret?: string;
+    /** Fixed clock (default). */
+    now?: () => number;
+}
+export interface TestApp extends IntegrationApp {
+    /** Signs a webhook payload (body + headers ready for `server.inject`). */
+    signWebhook(payload: object, ts?: number): {
+        body: string;
+        headers: Record<string, string>;
+    };
+    /** Signs an INBOUND call (route /inbound) with the per-installation secret. */
+    signInbound(installationId: string, payload: object, ts?: number): {
+        body: string;
+        headers: Record<string, string>;
+    };
+}
+/** Builds a test app: in-memory store, stub SDK client, webhook signing. */
+export declare function makeTestApp<S>(integration: Integration<S>, opts?: TestAppOptions): TestApp;
+/**
+ * Offline STUB SDK client: a real client whose axios adapter is replaced by a
+ * function returning empty `ok` envelopes (empty lists, create→id 1, bulk→counters
+ * at 0). Enough to exercise the lifecycle / provisioning without network access.
+ * Can be overridden via `opts.spm`.
+ */
+export declare function makeStubSpmClient(): SpmHttpClient;
+/** Request seen by a scriptable stub (request body already deserialized). */
+export type SpmStubRequest = {
+    method: string;
+    url: string;
+    body: any;
+};
+/** Scripted reply: `body` = RAW HTTP body. `status >= 400` → error (axios rejection). */
+export interface SpmStubReply {
+    status?: number;
+    body?: unknown;
+}
+/**
+ * SCRIPTABLE STUB SDK client: the axios adapter delegates to `handler(method,url,body)`.
+ * Statuses < 300 resolve; statuses >= 400 REJECT like axios (the SDK then encodes
+ * `{ ok:false, statusCode }`). Required to test error paths (4xx/5xx, 409 idempotent)
+ * that `makeStubSpmClient` (always 200) does not cover.
+ */
+export declare function makeScriptedSpmClient(handler: (req: SpmStubRequest) => SpmStubReply): SpmHttpClient;

package/dist/testing/harness.js

@@ -0,0 +1,110 @@
+import { randomBytes } from 'node:crypto';
+import { SpmClient } from '@shopimind/sdk-js';
+import { createIntegrationApp } from '../runtime/create-app.js';
+import { createLogger } from '../logging/logger.js';
+import { signShopimindBody } from '../security/signature.js';
+import { ensureInboundSecret } from '../lifecycle/inbound.js';
+/** Builds a test app: in-memory store, stub SDK client, webhook signing. */
+export function makeTestApp(integration, opts = {}) {
+    // Guard: this harness is NEVER intended for production (test keys/server).
+    if (process.env.NODE_ENV === 'production') {
+        throw new Error('makeTestApp() is for tests only and forbidden in production');
+    }
+    const secret = opts.secret ?? 'test_' + randomBytes(16).toString('hex');
+    const fixedNow = opts.now ?? (() => 1_700_000_000_000);
+    const stub = opts.spm ?? makeStubSpmClient();
+    const app = createIntegrationApp(integration, {
+        databasePath: ':memory:',
+        webhookSecret: secret,
+        credentialsKey: randomBytes(32).toString('hex'),
+        makeSpmClient: () => stub,
+        autoBackfillOnActivate: false,
+        autoSync: false,
+        now: fixedNow,
+        logger: createLogger({ sink: () => { } }),
+    });
+    return {
+        ...app,
+        signWebhook(payload, ts = Math.floor(fixedNow() / 1000)) {
+            const body = JSON.stringify(payload);
+            return {
+                body,
+                headers: {
+                    'content-type': 'application/json',
+                    'x-shopimind-timestamp': String(ts),
+                    'x-shopimind-signature': signShopimindBody(body, secret, ts),
+                },
+            };
+        },
+        signInbound(installationId, payload, ts = Math.floor(fixedNow() / 1000)) {
+            const inboundSecret = ensureInboundSecret(app.repos.state, installationId);
+            const body = JSON.stringify(payload);
+            return {
+                body,
+                headers: {
+                    'content-type': 'application/json',
+                    'x-integration-installation': installationId,
+                    'x-integration-timestamp': String(ts),
+                    'x-integration-signature': signShopimindBody(body, inboundSecret, ts),
+                },
+            };
+        },
+    };
+}
+/**
+ * Offline STUB SDK client: a real client whose axios adapter is replaced by a
+ * function returning empty `ok` envelopes (empty lists, create→id 1, bulk→counters
+ * at 0). Enough to exercise the lifecycle / provisioning without network access.
+ * Can be overridden via `opts.spm`.
+ */
+export function makeStubSpmClient() {
+    const client = SpmClient.getClient('v1', 'test', { baseUrl: 'http://localhost', retry: false, labelSource: null });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    client.defaults.adapter = async (config) => {
+        const method = (config.method ?? 'get').toLowerCase();
+        const url = config.url ?? '';
+        const body = stubBody(method, url);
+        return { data: { statusCode: 200, data: body }, status: 200, statusText: 'OK', headers: {}, config };
+    };
+    return client;
+}
+function stubBody(method, url) {
+    if (method === 'get') {
+        if (/custom-data-definitions\/\d+$/.test(url))
+            return { id_definition: 1, name: 'noop', fields: [] };
+        return []; // list endpoints
+    }
+    if (url === 'data-sources')
+        return { id_data_source: 1, label: 'noop', type: 'api' };
+    if (url === 'custom-data-definitions')
+        return { id_definition: 1, name: 'noop' };
+    // bulk-save / other writes → neutral counters
+    return { sent_count: 0, rejected_count: 0, failed_count: 0, rejected_items: [] };
+}
+/**
+ * SCRIPTABLE STUB SDK client: the axios adapter delegates to `handler(method,url,body)`.
+ * Statuses < 300 resolve; statuses >= 400 REJECT like axios (the SDK then encodes
+ * `{ ok:false, statusCode }`). Required to test error paths (4xx/5xx, 409 idempotent)
+ * that `makeStubSpmClient` (always 200) does not cover.
+ */
+export function makeScriptedSpmClient(handler) {
+    const client = SpmClient.getClient('v1', 'test', { baseUrl: 'http://localhost', retry: false, labelSource: null });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    client.defaults.adapter = async (config) => {
+        const method = String(config.method ?? 'get').toLowerCase();
+        const url = String(config.url ?? '');
+        const body = config.data ? JSON.parse(config.data) : undefined;
+        const r = handler({ method, url, body });
+        const status = r.status ?? 200;
+        const response = { data: r.body ?? {}, status, statusText: '', headers: {}, config };
+        if (status >= 200 && status < 300)
+            return response;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const err = new Error(`Request failed with status code ${status}`);
+        err.isAxiosError = true;
+        err.response = response;
+        err.config = config;
+        throw err;
+    };
+    return client;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@shopimind/integration-kit-js",
+  "version": "1.0.0",
+  "description": "Foundation for building ShopiMind integrations: a runtime plus typed, once-tested primitives (HMAC webhook signatures, encryption, log redaction, a safe cursor-based sync engine, pagination/concurrency, persistence, ShopiMind SDK re-export, idempotent provisioning, secured inbound middleware, HTTP server). An integration only writes pure functions and declarations passed to defineIntegration.",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shopimind/integration-kit-js.git"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "volta": {
+    "node": "18.20.8",
+    "yarn": "1.22.22"
+  },
+  "packageManager": "yarn@1.22.22",
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "tsc -b --clean"
+  },
+  "dependencies": {
+    "@hapi/hapi": "^21.3.10",
+    "@shopimind/sdk-js": "^1.0.0",
+    "better-sqlite3": "^11.3.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/node": "^18.19.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.0"
+  }
+}