@dataships/sdk 0.0.0-stage → 2.0.0

package/dist/types-Bfm_pCq7.d.ts

@@ -0,0 +1,233 @@
+type Channel = "EMAIL" | "SMS" | "WHATSAPP";
+/** Consent type of a v2 consent entry. `PENDING_IDENTITY` and `NO_WIDGET_DISPLAYED` never reach the client. */
+type ConsentType = "OPT_IN" | "OPT_OUT" | "NO_OPT_IN" | "NO_OPT_OUT" | "NONE" | "OPT_IN_PRE_TICKED" | "PENDING_IDENTITY" | "NO_WIDGET_DISPLAYED";
+declare const SUPPORTED_LOCALES: readonly ["en", "es", "de", "pt", "ro", "hr", "da", "fi", "fr", "hu", "it", "nb", "pl", "sk", "sv", "nl", "el", "cs", "zh", "ja", "is"];
+type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
+/**
+ * Which contact the consent-session envelope carries at the top
+ * level. `EMAIL` ⇒ email address, `PHONE` ⇒ phone number.
+ */
+type IdentifierType = "EMAIL" | "PHONE";
+type Environment = "production" | "staging" | "local";
+/** The consent-session handle `saveConsent` and `startHeartbeat` operate on. */
+interface SessionIds {
+    consentSessionId: string | null;
+}
+/** Resolved top-level identifier for the consent-session envelope. */
+interface ConsentSessionIdentifier {
+    identifier: string | null;
+    identifierType: IdentifierType;
+}
+/**
+ * Browser credentials for the consent-session protocol: the merchant's public
+ * key (`X-Api-Key`) and the JWT their server minted for this page, sent
+ * verbatim as `Authorization: Bearer`. The SDK never decodes or refreshes it;
+ * rotate it with {@link DatashipsClient.setToken}, or pass a
+ * {@link TokenProviderAuth} instead when the platform hands out short-lived
+ * tokens on demand.
+ */
+interface PublicKeyAuth {
+    publicKey: string;
+    token: string;
+    getToken?: never;
+}
+/**
+ * Browser credentials whose token is fetched before every request, retries and
+ * heartbeats included, for platforms that mint short-lived tokens on demand
+ * (Shopify's `shopify.sessionToken.get()`). The SDK never caches the result.
+ * Exclusive with {@link PublicKeyAuth.token}; `setToken()` does not apply.
+ */
+interface TokenProviderAuth {
+    publicKey: string;
+    getToken: () => string | Promise<string>;
+    token?: never;
+}
+/**
+ * Server-to-server credentials: the merchant's server key alone (`X-Api-Key`,
+ * no token). Only accepted by `DatashipsServerClient` from `@dataships/sdk/server`.
+ */
+interface ServerKeyAuth {
+    serverKey: string;
+}
+type CustomerApiAuth = PublicKeyAuth | ServerKeyAuth;
+/**
+ * UNSAFE escape hatch for a merchant with no server to mint tokens: the server
+ * key itself in the page, sent alone as `X-Api-Key`. Anyone who views source
+ * can then open sessions, save consent and submit orders as that merchant
+ * until the key is revoked; revocation is the only remedy. The SDK warns once
+ * at construction and tags every request so the exposure is never silent.
+ * Prefer `PublicKeyAuth` wherever a token can be minted.
+ */
+interface UnsafeServerKeyAuth {
+    unsafeServerKey: string;
+}
+/** Credentials the browser client accepts: the safe pair (fixed or provided token), or the explicit unsafe escape hatch. */
+type BrowserAuth = PublicKeyAuth | TokenProviderAuth | UnsafeServerKeyAuth;
+interface UpsertSessionInput {
+    /** The only channel-related input: PHONE covers SMS and WhatsApp, the server picks the channels. */
+    identifierType: IdentifierType;
+    /** Contact for that type. Omit (or pass null) to let the adapter resolve the server-known value. */
+    identifier?: string | null;
+    /** Trusted as the geolocation source when present; otherwise the connection IP is used. */
+    userIp?: string;
+    /**
+     * How the copy comes back: `json` (the API default) leaves plain strings to
+     * format client-side, `html` applies links and emphasis to `text` and
+     * `consentDescription`.
+     */
+    format?: ConsentCopyFormat;
+}
+type ConsentCopyFormat = "json" | "html";
+/**
+ * Server-side upsert input: the connection IP is the merchant's server, so the
+ * user's IP must always be supplied for geolocation.
+ */
+interface ServerUpsertSessionInput extends UpsertSessionInput {
+    userIp: string;
+}
+/** Widget copy for one channel. Every field may be null; render what is present. */
+interface ConsentWidgetConfig {
+    text: string | null;
+    consentDescription: string | null;
+    marketingInformation: string | null;
+    policyURL: string | null;
+    mobileTermsOfServiceURL: string | null;
+    privacyEmail: string | null;
+    /**
+     * What the copy's placeholders resolve to; null when it uses none. In `json` copy,
+     * render `{{MARKETING_PREFERENCES}}` as the marketing modal link showing
+     * `MARKETING_PREFERENCES` as is. `html` copy has it rendered already.
+     */
+    placeholderValues?: WidgetCopyPlaceholderValues | null;
+}
+interface WidgetCopyPlaceholderValues {
+    MARKETING_PREFERENCES?: string;
+}
+/** One channel that renders a widget: its consent record plus the copy. */
+interface ConsentItem {
+    channel: Channel;
+    consentType: ConsentType;
+    checked: boolean;
+    widgetConfig: ConsentWidgetConfig;
+}
+/**
+ * `POST /v1/consent-session` response. An empty `consents` means there is
+ * nothing to render; `consentSessionId` is null only in that normalised
+ * nothing-to-render case (see `upsertSession`).
+ */
+interface UpsertSessionResponse {
+    consentSessionId: string | null;
+    consents: ConsentItem[];
+    /** Phone sessions only: whether the user must verify with a one-time code. Null for EMAIL. */
+    userVerificationRequired: boolean | null;
+    lastHeartbeat: string | null;
+    /**
+     * The identifier the session holds for the requested type, so a widget that
+     * lost what the user typed (a reload, a remount) can refill its field. Null
+     * while the session has none; absent from a core-api that predates it.
+     */
+    identifier?: string | null;
+}
+/**
+ * Platform adapter for the `/v1/consent-session` protocol. It declares the
+ * `integration.type` discriminator, resolves the top-level identifier and
+ * returns the integration-specific fields from `getSessionContext()` (the
+ * client injects `type` under `integration` and `locale` at the top level; the
+ * merchant comes from the `X-Api-Key` header, never from the body).
+ */
+interface ConsentSessionAdapter<TContext = unknown> {
+    /**
+     * Adapter identifier reported via `X-Dataships-App` (e.g. "SalesforceAdapter").
+     * Used to distinguish which SDK adapter sourced the request.
+     */
+    readonly name: string;
+    /**
+     * Always `"consent-session"`, the only protocol the SDK speaks. Kept as a
+     * constant marker because integrations check it to recognise an SDK adapter.
+     */
+    readonly sessionApi: "consent-session";
+    /** ISO 639-1 locale code from the SupportedLocale union. */
+    getLocale(): SupportedLocale;
+    /** The integration-specific fields merged under `integration` on every upsert. */
+    getSessionContext(): Promise<TContext>;
+    /**
+     * When true, the client serves synthetic responses instead of making live
+     * network calls: `upsertSession` returns
+     * {@link getPreviewUpsertResponse}; `saveConsent`, the heartbeat, the OTP
+     * calls and `submitSession` resolve without a request. No credentials are
+     * needed. Used to style a widget in an editor or sandbox without hitting the
+     * API. Defaults to live behaviour when absent.
+     */
+    previewMode?: boolean;
+    /** Synthetic upsert response served when {@link previewMode} is true, for the requested identifier type. */
+    getPreviewUpsertResponse?(identifierType: IdentifierType): UpsertSessionResponse;
+    /** `integration.type` discriminator, e.g. "SALESFORCE_SNIPPET". */
+    readonly integrationType: string;
+    /**
+     * Resolves the top-level `identifier` / `identifierType` for `upsertSession`
+     * from the adapter's own data. An explicit `upsertSession({ identifier })`
+     * takes precedence, e.g. an email the buyer types mid-checkout.
+     */
+    getIdentifier(identifierType: IdentifierType): ConsentSessionIdentifier | Promise<ConsentSessionIdentifier>;
+    /**
+     * The `datashipsSessionId` beacon the adapter sent on its upserts, when it
+     * owns one. `submitSession` uses it as the default id to complete, so a
+     * browser integration never has to carry the beacon itself. Adapters that
+     * have no beacon (server-side, Salesforce) leave this undefined and callers
+     * pass `datashipsSessionId` explicitly.
+     */
+    getDatashipsSessionId?(): string;
+    /**
+     * Discard the beacon after a completed submit so the next collection on this
+     * browser opens a new session instead of touching the completed one.
+     */
+    resetDatashipsSessionId?(): void;
+}
+/**
+ * The shopper as the merchant knows them at completion. Both names are
+ * required and non-blank (core-api validates `NotBlank`). Contact details never
+ * travel here: the identifier is what the widget collected on the upsert.
+ */
+interface SubmitConsentSessionUser {
+    firstName: string;
+    lastName: string;
+}
+/**
+ * `integration` details of a `CUSTOM_PLATFORM_CHECKOUT` submit: the order the
+ * shopper placed. Amounts are in the merchant integration's currency.
+ */
+interface CustomPlatformCheckoutSubmitDetails {
+    /** Merchant order id (max 255). */
+    id: string;
+    /** Order total as a number, zero allowed. */
+    total: number;
+    /** Billing country, ISO 3166-1 alpha-2; drives the legal basis. Case-insensitive here, sent uppercased. */
+    billingCountryCode: string;
+    /** When the order was placed; defaults server-side to the time the submit arrives. */
+    submittedAt?: string | Date;
+}
+/**
+ * Input to `submitSession`: the completion signal for every session opened
+ * under one beacon. `details` is the flow-specific payload merged under
+ * `integration` next to the adapter's `type`; for a checkout that is the
+ * order ({@link CustomPlatformCheckoutSubmitDetails}).
+ */
+interface SubmitSessionInput<TDetails = CustomPlatformCheckoutSubmitDetails> {
+    /**
+     * The beacon sent on the upserts. Browser clients default to the adapter's
+     * own beacon; the server client requires it, since a server holds none.
+     */
+    datashipsSessionId?: string;
+    /** The shopper's names; required by core-api. */
+    user: SubmitConsentSessionUser;
+    details: TDetails;
+    /**
+     * Discard the adapter's beacon once the submit is accepted, so the next
+     * collection on this browser starts a new session. Defaults to true; has no
+     * effect when `datashipsSessionId` was passed explicitly.
+     */
+    resetBeacon?: boolean;
+}
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export { type BrowserAuth as B, type ConsentSessionAdapter as C, type Environment as E, type FetchLike as F, type IdentifierType as I, type PublicKeyAuth as P, type SupportedLocale as S, type TokenProviderAuth as T, type UpsertSessionResponse as U, type WidgetCopyPlaceholderValues as W, type ConsentSessionIdentifier as a, type UpsertSessionInput as b, type Channel as c, type SessionIds as d, type SubmitSessionInput as e, type CustomerApiAuth as f, type UnsafeServerKeyAuth as g, type ConsentCopyFormat as h, type ConsentItem as i, type ConsentType as j, type ConsentWidgetConfig as k, type CustomPlatformCheckoutSubmitDetails as l, SUPPORTED_LOCALES as m, type ServerKeyAuth as n, type SubmitConsentSessionUser as o, type ServerUpsertSessionInput as p };

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "@dataships/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "Dataships client SDK — transport and consent-session lifecycle for the Dataships consent-session API. Platform-agnostic core with adapters per integration (Shopify checkout, Salesforce, custom platform, …).",
+  "private": false,
+  "license": "Apache-2.0",
+  "author": "Dataships",
+  "homepage": "https://dataships.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/dataships/platform/dataships-sdk.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "unpkg": "./dist/dataships.min.js",
+  "jsdelivr": "./dist/dataships.min.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./adapters/shopify-checkout": {
+      "types": "./dist/adapters/shopify-checkout/index.d.ts",
+      "import": "./dist/adapters/shopify-checkout/index.js"
+    },
+    "./adapters/salesforce": {
+      "types": "./dist/adapters/salesforce/index.d.ts",
+      "import": "./dist/adapters/salesforce/index.js"
+    },
+    "./adapters/custom-platform-checkout": {
+      "types": "./dist/adapters/custom-platform-checkout/index.d.ts",
+      "import": "./dist/adapters/custom-platform-checkout/index.js"
+    },
+    "./adapters/custom-platform-signup": {
+      "types": "./dist/adapters/custom-platform-signup/index.d.ts",
+      "import": "./dist/adapters/custom-platform-signup/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsup && node scripts/integrity.mjs",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "test": "vitest",
+    "test:once": "vitest run",
+    "test:ci": "vitest run --coverage.enabled --reporter=junit --outputFile=./junit.xml",
+    "prepublishOnly": "yarn build",
+    "check:package": "sh scripts/check-package.sh",
+    "smoke:cdn": "node scripts/smoke-cdn.mjs",
+    "verify:npm": "sh scripts/verify-npm.sh"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@types/node": "^20.12.11",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "@vitest/coverage-v8": "^3.2.6",
+    "eslint": "^8.57.0",
+    "jsdom": "^24.0.0",
+    "msw": "^2.4.0",
+    "publint": "^0.3.25",
+    "tsup": "^8.3.0",
+    "typescript": "^5.4.0",
+    "vitest": "^3.2.6"
+  },
+  "packageManager": "yarn@1.22.22",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}