@shopimind/integration-kit-js 1.0.0 → 1.2.0

package/dist/contracts/sdk.d.ts

@@ -37,9 +37,18 @@ export interface NewCustomDataDefinition {
     description?: string;
     unique_keys?: string[];
     fields: NewCustomDataField[];
+    /**
+     * Schema-level relationships to other definitions (forwarded as-is to the API).
+     * `sourceField` is a field of THIS definition; it links to `targetSchema` — a
+     * `'system'` schema (e.g. `contacts`, `products`) or another `'custom'` definition
+     * (by its numeric id) — optionally matched on `targetField` (defaults to the
+     * target's id). Mirrors the API's relationship DTO; `custom`→`custom` is supported.
+     */
     relationships?: Array<{
-        target: string;
-        by: string;
+        sourceField: string;
+        targetSchemaType: 'system' | 'custom';
+        targetSchema: string;
+        targetField?: string;
     }>;
 }
 /** Order status to provision (declaration). */

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from './sync/cursor.js';
 export * from './sync/engine.js';
 export * from '@shopimind/sdk-js';
 export * from './sdk/source-scope.js';
+export * from './sdk/custom-data-scope.js';
 export type { BulkResult, SendBulk, SendBulkOptions } from './sdk/send-bulk.js';
 export * from './provisioning/ensure.js';
 export * from './provisioning/runner.js';

package/dist/index.js

@@ -18,6 +18,8 @@ export * from './sync/engine.js';
 export * from '@shopimind/sdk-js';
 // Provisioned source helper (`ctx.withSource` -> SourceHandle).
 export * from './sdk/source-scope.js';
+// Provisioned custom data helper (`ctx.customData` -> CustomDataHandle).
+export * from './sdk/custom-data-scope.js';
 // Idempotent provisioning + plan runner
 export * from './provisioning/ensure.js';
 export * from './provisioning/runner.js';

package/dist/integration/types.d.ts

@@ -2,6 +2,7 @@ import type { ConfigSchema, RawConfigs, WidgetDeclaration, NewDataSource, NewCus
 import type { SpmHttpClient } from '@shopimind/sdk-js';
 import type { SourceHandle } from '../sdk/source-scope.js';
 import type { SendBulk } from '../sdk/send-bulk.js';
+import type { CustomDataHandle } from '../sdk/custom-data-scope.js';
 import type { IntegrationStateRepo } from '../store/repositories.js';
 import type { CursorRow } from '../store/types.js';
 import type { Logger } from '../logging/logger.js';
@@ -58,6 +59,13 @@ export interface IntegrationContext<S> {
      * (Also namespace your identifiers: the source alone does not isolate them.)
      */
     withSource(sourceKey: string): SourceHandle;
+    /**
+     * Handle for a PROVISIONED custom data definition (declared in
+     * `provisioning.customData`): its numeric `id` plus a safe `save(records)`.
+     * `name` must match a definition declared in `provisioning.customData`.
+     * The custom-data counterpart of {@link IntegrationContext.withSource}.
+     */
+    customData(name: string): CustomDataHandle;
 }
 export interface SyncWindow {
     since: Date | null;

package/dist/lifecycle/dispatcher.js

@@ -6,6 +6,7 @@ import { runProvisioning } from '../provisioning/runner.js';
 import { ensureInboundSecret } from './inbound.js';
 import { makeWithSource } from '../sdk/source-scope.js';
 import { makeSendBulk } from '../sdk/send-bulk.js';
+import { makeCustomData } from '../sdk/custom-data-scope.js';
 export const ACCESS_TOKEN_KEY = '__access_token';
 /** State key where the provisioning result (sourceIds/defIds) is stored. */
 export const PROVISIONING_KEY = '__provisioning';
@@ -247,6 +248,7 @@ function buildContext(id, deps) {
         setExternalAccount: (acc) => deps.repos.installs.setExternalAccount(id, acc.id, acc.name ?? null),
         inboundSecret: ensureInboundSecret(deps.repos.state, id),
         withSource: makeWithSource(deps.repos.state, id, PROVISIONING_KEY, sendBulk),
+        customData: makeCustomData(deps.repos.state, id, PROVISIONING_KEY, sendBulk, spm),
     };
 }
 /** Context without an installation (config wizard): the ShopiMind SDK is not callable here. */
@@ -264,6 +266,9 @@ function ephemeralContext(configs, deps) {
         withSource: () => {
             throw new Error('withSource is unavailable during the configuration wizard (no installation)');
         },
+        customData: () => {
+            throw new Error('customData is unavailable during the configuration wizard (no installation)');
+        },
     };
 }
 async function runHookSafe(hook, id, deps) {

package/dist/runtime/create-app.js

@@ -8,6 +8,7 @@ import { runIntegrationSync } from '../sync/engine.js';
 import { ACCESS_TOKEN_KEY, PROVISIONING_KEY } from '../lifecycle/dispatcher.js';
 import { ensureInboundSecret } from '../lifecycle/inbound.js';
 import { makeWithSource } from '../sdk/source-scope.js';
+import { makeCustomData } from '../sdk/custom-data-scope.js';
 import { makeSendBulk } from '../sdk/send-bulk.js';
 import { createRateLimiter } from './rate-limiter.js';
 import { createServer } from '../http/server.js';
@@ -52,6 +53,7 @@ export function createIntegrationApp(integration, opts) {
             setExternalAccount: (acc) => repos.installs.setExternalAccount(id, acc.id, acc.name ?? null),
             inboundSecret: ensureInboundSecret(repos.state, id),
             withSource: makeWithSource(repos.state, id, PROVISIONING_KEY, sendBulk),
+            customData: makeCustomData(repos.state, id, PROVISIONING_KEY, sendBulk, spm),
         };
     };
     // Per-installation overlap lock: prevents a post-activation backfill, a scheduled
@@ -74,6 +76,7 @@ export function createIntegrationApp(integration, opts) {
                 cursors: repos.cursors,
                 runs: repos.runs,
                 makeSource: (sb) => makeWithSource(repos.state, id, PROVISIONING_KEY, sb),
+                makeCustomData: (sb) => makeCustomData(repos.state, id, PROVISIONING_KEY, sb, base.spm),
             }, { fullBackfill: o?.full ?? false, backfillDays });
         }
         finally {

package/dist/sdk/custom-data-scope.d.ts

@@ -0,0 +1,24 @@
+import { type SpmHttpClient } from '@shopimind/sdk-js';
+import type { IntegrationStateRepo } from '../store/repositories.js';
+import type { BulkResult, SendBulk, SendBulkOptions } from './send-bulk.js';
+/**
+ * Handle for a PROVISIONED custom data definition. Exposes its numeric `id`
+ * (resolved by name) plus a `save()` that upserts records into it through the
+ * safe bulk primitive (chunked, throws on a transport failure, surfaces per-item
+ * rejections). The counterpart of {@link SourceHandle} for custom data: a data
+ * source tags base entities, whereas a custom data definition stores its own
+ * records — so the handle exposes `save()` rather than `tag()`.
+ */
+export interface CustomDataHandle {
+    /** Numeric `id` of the provisioned custom data definition (resolved by name). */
+    readonly id: number;
+    /** Safe upsert of records into this definition (matched by its unique keys). */
+    save<T extends object>(records: T[], opts?: SendBulkOptions): Promise<BulkResult>;
+}
+/**
+ * Builds `ctx.customData`: resolves the numeric id of a PROVISIONED custom data
+ * definition (from the integration state, by `name`) and returns a
+ * {@link CustomDataHandle}. Throws if the definition was not declared in
+ * `provisioning.customData` (the symmetric guard of {@link makeWithSource}).
+ */
+export declare function makeCustomData(state: IntegrationStateRepo, installationId: string, provisioningKey: string, sendBulk: SendBulk, spm: SpmHttpClient): (name: string) => CustomDataHandle;

package/dist/sdk/custom-data-scope.js

@@ -0,0 +1,32 @@
+import { SpmCustomDataRecords } from '@shopimind/sdk-js';
+/**
+ * Builds `ctx.customData`: resolves the numeric id of a PROVISIONED custom data
+ * definition (from the integration state, by `name`) and returns a
+ * {@link CustomDataHandle}. Throws if the definition was not declared in
+ * `provisioning.customData` (the symmetric guard of {@link makeWithSource}).
+ */
+export function makeCustomData(state, installationId, provisioningKey, sendBulk, spm) {
+    return (name) => {
+        const raw = state.get(installationId, provisioningKey);
+        // Parse defensively: a corrupt/unreadable persisted blob is treated as
+        // "nothing provisioned" and surfaces as the business error below, never as
+        // an opaque SyntaxError.
+        let defIds = {};
+        if (raw) {
+            try {
+                defIds = JSON.parse(raw).defIds ?? {};
+            }
+            catch {
+                defIds = {};
+            }
+        }
+        const id = defIds[name];
+        if (id == null) {
+            throw new Error(`customData("${name}"): custom data definition not provisioned — declare it in provisioning.customData`);
+        }
+        return {
+            id,
+            save: (records, opts) => sendBulk(() => SpmCustomDataRecords.bulkSave(spm, id, records, { chunk: true, ...opts })),
+        };
+    };
+}

package/dist/sync/engine.d.ts

@@ -1,6 +1,7 @@
 import type { CursorRepo, RunRepo } from '../store/repositories.js';
 import type { Integration, IntegrationContext, SyncWindow } from '../integration/types.js';
 import type { SourceHandle } from '../sdk/source-scope.js';
+import type { CustomDataHandle } from '../sdk/custom-data-scope.js';
 import { type SendBulk } from '../sdk/send-bulk.js';
 export interface SyncOptions {
     fullBackfill?: boolean;
@@ -32,6 +33,11 @@ export interface SyncDeps {
      * runtime, which knows the installation + provisioning state.
      */
     makeSource: (sendBulk: SendBulk) => (sourceKey: string) => SourceHandle;
+    /**
+     * Builds `customData` bound to a given `sendBulk`, so `customData(name).save(...)`
+     * inside a step feeds the step's reject accumulator.
+     */
+    makeCustomData: (sendBulk: SendBulk) => (name: string) => CustomDataHandle;
 }
 /**
  * Runs the enabled sync steps of an integration. The cursor is managed HERE,

package/dist/sync/engine.js

@@ -69,6 +69,7 @@ async function runOneSource(step, base, deps, sourceKey, win) {
         mapConcurrent: mapWithConcurrency,
         sendBulk: stepSendBulk,
         withSource: deps.makeSource(stepSendBulk),
+        customData: deps.makeCustomData(stepSendBulk),
     };
     let result;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopimind/integration-kit-js",
-  "version": "1.0.0",
+  "version": "1.2.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": {