@mycreat-labs/integrations-sdk 0.0.0-stage → 0.1.1

package/dist/types-Y4-DoJ1A.d.ts

@@ -0,0 +1,260 @@
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+type Purpose = "identity" | "connect";
+type Scope = {
+    namespace: string;
+    ownerId: string;
+};
+type VerifiedIdentity = {
+    provider: string;
+    issuer: string;
+    subject: string;
+    identityNamespace: string;
+    email?: string;
+    emailVerified: boolean;
+    name?: string;
+    username?: string;
+};
+type CredentialMaterial = {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    scopes?: string[];
+    extra?: {
+        [key: string]: Json;
+    };
+};
+type RemoteAccount = {
+    id: string;
+    label: string;
+    metadata?: {
+        [key: string]: Json;
+    };
+};
+type Resource = {
+    id: string;
+    type: string;
+    name: string;
+    url?: string;
+    metadata?: {
+        [key: string]: Json;
+    };
+};
+type ResourcePage = {
+    items: Resource[];
+    nextCursor?: string;
+};
+type ProviderContext = {
+    credentials: CredentialMaterial;
+    signal?: AbortSignal;
+    fetch: typeof globalThis.fetch;
+};
+type ActionContext = ProviderContext & {
+    operationId: string;
+    checkpoint: Json;
+    saveCheckpoint(value: Json): Promise<void>;
+};
+type ActionDefinition = {
+    validate(input: unknown): Json;
+    execute(input: Json, context: ActionContext): Promise<Json>;
+    reconcile?(input: Json, context: ActionContext): Promise<{
+        resolved: true;
+        result: Json;
+    } | {
+        resolved: false;
+    }>;
+};
+type AuthorizationInput = {
+    state: string;
+    verifier: string;
+    challenge: string;
+    nonce: string;
+    purpose: Purpose;
+};
+type AuthorizationResult = {
+    identity?: VerifiedIdentity;
+    account?: RemoteAccount;
+    credentials?: CredentialMaterial;
+};
+interface IntegrationProvider {
+    key: string;
+    registrationId: string;
+    purposes: readonly Purpose[];
+    authorization?: {
+        url(input: AuthorizationInput): string;
+        exchange(input: {
+            code: string;
+            verifier: string;
+            nonce: string;
+            purpose: Purpose;
+            signal?: AbortSignal;
+        }, fetch: typeof globalThis.fetch): Promise<AuthorizationResult>;
+    };
+    verifyNative?(input: {
+        idToken: string;
+        nonce: string;
+        authorizationCode?: string;
+    }, fetch: typeof globalThis.fetch): Promise<VerifiedIdentity>;
+    resources?(input: {
+        cursor?: string;
+        query?: string;
+        parentId?: string;
+    }, context: ProviderContext): Promise<ResourcePage>;
+    refresh?(credentials: CredentialMaterial, context: {
+        fetch: typeof globalThis.fetch;
+        signal?: AbortSignal;
+    }): Promise<CredentialMaterial>;
+    revoke?(credentials: CredentialMaterial, context: {
+        fetch: typeof globalThis.fetch;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    actions?: Readonly<Record<string, ActionDefinition>>;
+}
+type SealedValue = {
+    keyId: string;
+    value: string;
+};
+interface TokenVault {
+    seal(value: Json, context: string): Promise<SealedValue>;
+    open(value: SealedValue, context: string): Promise<Json>;
+}
+type Flow = {
+    id: string;
+    namespace: string;
+    ownerId: string;
+    provider: string;
+    registrationId: string;
+    purpose: Purpose;
+    bindingHash: string;
+    expiresAt: number;
+    secret: SealedValue;
+    authorizationEpoch?: number;
+    connectionId?: string;
+    generation?: number;
+};
+type Grant = {
+    id: string;
+    namespace: string;
+    ownerId: string;
+    provider: string;
+    registrationId: string;
+    account: RemoteAccount;
+    version: number;
+    status: "active" | "reauth_required" | "revoked";
+    credentials: SealedValue;
+    expiresAt?: number;
+    refreshLease?: string;
+    refreshUntil?: number;
+    authorizationLease?: string;
+    authorizationUntil?: number;
+};
+type Connection = {
+    id: string;
+    namespace: string;
+    ownerId: string;
+    provider: string;
+    registrationId: string;
+    grantId: string;
+    account: RemoteAccount;
+    generation: number;
+    status: "active" | "reauth_required" | "revoked";
+    createdAt: number;
+    updatedAt: number;
+};
+type OperationStatus = "pending" | "running" | "succeeded" | "failed" | "blocked" | "outcome_unknown" | "cancelled";
+type Operation = {
+    id: string;
+    namespace: string;
+    ownerId: string;
+    connectionId: string;
+    generation: number;
+    action: string;
+    idempotencyKey: string;
+    fingerprint: string;
+    input: SealedValue;
+    hostContext?: Json;
+    status: OperationStatus;
+    version: number;
+    attempts: number;
+    authRecoveries?: number;
+    availableAt: number;
+    checkpoint: Json;
+    dispatching: boolean;
+    leaseToken?: string;
+    leaseUntil?: number;
+    result?: Json;
+    errorCode?: string;
+    createdAt: number;
+    updatedAt: number;
+};
+type IntegrationEvent = {
+    id: string;
+    namespace: string;
+    ownerId: string;
+    operationId: string;
+    type: string;
+    createdAt: number;
+    data: Json;
+};
+interface IntegrationTransaction {
+    readonly nativeContext?: unknown;
+    lockScope(scope: Scope, allowErased?: boolean): Promise<boolean>;
+    authorizationEpoch(scope: Scope, key: string, advance?: boolean): Promise<number>;
+    markOwnerErased(scope: Scope): Promise<void>;
+    assertAccountOwner(scope: Scope, provider: string, registrationId: string, accountId: string): Promise<void>;
+    collectGarbage(namespace: string, now: number, retentionMs: number): Promise<void>;
+    insertFlow(flow: Flow): Promise<void>;
+    consumeFlow(namespace: string, id: string, bindingHash: string, purpose: Purpose, now: number): Promise<Flow | null>;
+    insertGrant(grant: Grant): Promise<void>;
+    getGrant(scope: Scope, id: string, lock?: boolean): Promise<Grant | null>;
+    saveGrant(grant: Grant, expectedVersion: number): Promise<boolean>;
+    insertConnection(connection: Connection): Promise<void>;
+    getConnection(scope: Scope, id: string, lock?: boolean): Promise<Connection | null>;
+    listConnections(scope: Scope): Promise<Connection[]>;
+    saveConnection(connection: Connection, expectedGeneration: number): Promise<boolean>;
+    insertOperation(operation: Operation): Promise<Operation>;
+    getOperation(scope: Scope, id: string, lock?: boolean): Promise<Operation | null>;
+    listOperations(scope: Scope, connectionId?: string): Promise<Operation[]>;
+    hasPendingRevocation(scope: Scope, connectionId: string): Promise<boolean>;
+    saveOperation(operation: Operation, expectedVersion: number, leaseToken?: string): Promise<boolean>;
+    claimOperation(namespace: string, id: string, version: number, now: number, leaseToken: string, leaseUntil: number): Promise<Operation | null>;
+    dueOperations(namespace: string, now: number, limit: number): Promise<Array<{
+        id: string;
+        version: number;
+    }>>;
+    recoverOperations(namespace: string, now: number): Promise<number>;
+    insertEvent(event: IntegrationEvent): Promise<void>;
+    listEvents(scope: Scope, after?: string): Promise<IntegrationEvent[]>;
+    eraseOwner(scope: Scope, preserveRevocations: boolean): Promise<void>;
+}
+interface IntegrationStore {
+    transaction<T>(work: (tx: IntegrationTransaction) => Promise<T>): Promise<T>;
+    assertCompatible(): Promise<void>;
+}
+type TaskMessage = {
+    taskId: string;
+    version: number;
+};
+interface QueueTransport {
+    publish(messages: TaskMessage[]): Promise<void>;
+    start(handler: (message: TaskMessage) => Promise<void>): Promise<void>;
+    stop(): Promise<void>;
+}
+type SdkLogger = {
+    info?(fields: Record<string, string | number | boolean>, message: string): void;
+    warn?(fields: Record<string, string | number | boolean>, message: string): void;
+    error?(fields: Record<string, string | number | boolean>, message: string): void;
+};
+interface ApiRateLimiter {
+    take(key: string): Promise<{
+        allowed: boolean;
+        retryAfterMs: number;
+    }>;
+}
+type HostHooks = {
+    beforeExecute?(context: unknown, operation: Operation, input: Json): Promise<void>;
+    onResult?(context: unknown, operation: Operation, event: IntegrationEvent, input: Json): Promise<void>;
+};
+
+export type { ApiRateLimiter as A, Connection as C, Flow as F, Grant as G, HostHooks as H, IntegrationStore as I, Json as J, Operation as O, Purpose as P, QueueTransport as Q, ResourcePage as R, Scope as S, TokenVault as T, VerifiedIdentity as V, IntegrationTransaction as a, IntegrationEvent as b, TaskMessage as c, IntegrationProvider as d, SdkLogger as e, ActionContext as f, ActionDefinition as g, AuthorizationInput as h, AuthorizationResult as i, CredentialMaterial as j, OperationStatus as k, ProviderContext as l, RemoteAccount as m, Resource as n, SealedValue as o };

package/docs/migration.md

@@ -0,0 +1,23 @@
+# Installation, migration and release ownership
+
+## New product
+
+The product owns the generated Prisma schema, migrations and deployment. Copy the SDK fragment and apply its SQL using the product migration runner. Keep SDK table names and constraints unchanged. At startup `assertCompatible` accepts storage schema 1; it never creates or upgrades tables. Supply the existing Prisma client, not a separate pool; bind native transactions for atomic business/operation writes. Optional peer adapters are installed by the product, and only selected provider factories are registered.
+
+API and Worker use the same pinned package and schema version within a product. An operation's dispatch version fences stale queue messages. Public contract, operation format and storage compatibility are separate concerns: additive package fixes do not authorize destructive DDL. Review migrations and retained operation compatibility before rolling upgrades. Rollback must preserve grant versions, leases, authorization fences and uncertain writes. Never reset state or downgrade by deleting SDK tables.
+
+## Existing Subtic
+
+The initial adoption delegates Notion and Raindrop protocol/HTTP handling to the packed SDK through legacy error adapters. Subtic's API shapes, database IDs, ciphertext/AAD, grants, refresh owner/lease, exports, subscriptions, tasks and checkpoints remain authoritative. There is no second SDK scheduler or refresher for these grants. Notion's configured API version and existing timeout policies remain pinned by its host. Safe-error classification must preserve partial writes and distinguish invalid HTTP-200 receipts from definite no-write errors.
+
+Subsequent storage/runtime migration is per provider and per connection: quiesce old execution, preserve an explicit ownership fence, translate durable state with a verified mapping, verify decryptability and in-flight task semantics, then activate the new owner. Unknown writes are reconciled, not re-exported. Shared upstream installations keep reference counting and last-reference revocation. Gmail Watch/history and old callbacks are separate migration work; Gmail, Readwise and Instapaper remain on their current host implementations in this initial release.
+
+## Existing Kiipu
+
+The initial host installs the packed SDK and adds new SDK storage alongside its account/content tables. Existing password/Apple login, sessions and Desktop/extension handoffs keep their product ownership. New Google/GitHub web login is enabled only by complete product-local configuration; external identity columns are additive. New Notion/Raindrop connections do not import Subtic credentials.
+
+The Kiipu staged migrations include the initial SDK schema plus owner-fence and unique external-account constraints. These were applied only to a dedicated local test database during implementation. Production migration and configuration remain a separate release step. The Worker requires the matching SDK package and product keyring; do not remove keys while encrypted records or durable cleanup still require them.
+
+## Package release
+
+Release immutable npm artifacts with semantic versions into an internal registry after separate publication authorization. Keep exact package versions, lockfile integrity and a source-to-artifact record. Local implementation uses a checked vendor tarball until a registry is available. Existing released versions must not be overwritten; replace development test artifacts only before first publication. Products upgrade independently and run their own consumer contracts before deployment.

package/docs/releases/0.1.0.md

@@ -0,0 +1,46 @@
+# 0.1.0 release — 2026-10-31
+
+Package: `@mycreat-labs/integrations-sdk@0.1.0`.
+Registry: `https://registry.npmjs.org/`. Access: public, explicitly approved by the owner.
+The repository `.npmrc` records this registry without credentials.
+Release source: `6e16f40120dcecfacaaeaf20e5537e93a842556b`, tag `npm-v0.1.0`.
+
+```sh
+npm install --save-exact @mycreat-labs/integrations-sdk@0.1.0
+```
+
+The anonymously downloaded npm archive matches both products' pinned vendor
+archives byte for byte:
+
+SHA-256: `94b4bff090d8322c7c610c4fbfe5a702a2e093d096bcdfba8b53825c27f3fc10`.
+The npm integrity and source inventory are recorded in `release-manifest.json`.
+Published archives must not be replaced in place.
+
+## Verification
+
+- SDK: 77 unit tests, 6 isolated PostgreSQL tests and 2 packed ESM/CJS tests passed.
+- A separate host installed the anonymously downloaded distribution and passed
+  strict TypeScript, real Prisma transaction rollback, authorization, durable
+  execution and transactional result projection checks.
+- Kiipu: 792 current-source unit tests, application typechecks and production builds passed.
+- Subtic: 69 relevant provider/runtime/probe unit tests passed; connector typechecks,
+  changed-file lint and production builds passed. Nine database tests in the focused
+  unit command were deliberately skipped; earlier isolated database acceptance is
+  documented in the consumer repository.
+
+## Production consumers
+
+| Product | Deployed code | Result |
+| --- | --- | --- |
+| Kiipu | `f6cee97fdab537e6bfbaef0d3d29d1e9eefd43b5` | API, Worker and Web healthy; five new migrations applied |
+| Subtic | `9380a609b77e38cb93b627b6a581578626ff29ea` | API, Web, primary/media/search workers and all five connector workers healthy |
+
+Production backups and the products' deployment/rollback scripts were used.
+Public login pages and their static assets passed HTTP checks. Kiipu remained
+ready through the shared gateway after Subtic's deployment.
+The five database/Redis containers retained their IDs and start times.
+
+Kiipu's independent OAuth registrations and integration encryption configuration
+are not yet present in production. Its third-party capabilities remain disabled
+until the product supplies these settings. Real-provider consent, remote writes,
+revocation and native-device acceptance were not performed in this release.

package/docs/security.md

@@ -0,0 +1,26 @@
+# Security model and provider behavior
+
+The SDK executes with host privileges. It does not sandbox untrusted plugins. Provider implementations and infrastructure adapters are reviewed code; owners, connection IDs and operations must always originate from authenticated product routes. Cross-product reuse is code reuse, not shared users, cookies, OAuth clients or secrets.
+
+Secrets are AES-256-GCM encrypted using a versioned key ID and AAD bound to namespace, owner, registration and grant/operation purpose. Wrong-context ciphertext is rejected. Preserve old keys for read compatibility during rotation; never silently fall back to another context or key. API responses should project connection/operation status rather than exposing internal sealed payloads or database records.
+
+Authorization uses one-time state, browser binding, PKCE/nonce where the provider supports them, fixed callback configuration, issuer/audience validation and native server challenges. Google and Apple JWT verification uses JOSE and bounded JWKS caching. GitHub requires verified primary email and discards its login access token after resolving identity. Login and connection purposes never interchange.
+
+Refresh owns a persistent versioned lease. An unknown rotating-token refresh is fenced for reauthorization. A definite HTTP-429 or local admission rejection clears only its lease and remains retryable. Notion does not guarantee an expires_in field; a confirmed no-write 401 can force one coordinated refresh, with a persistent per-operation recovery budget. An unknown write is never retried merely because authentication was refreshed.
+
+An authorization callback reserves existing same-provider grants across exchange, preventing a rotating refresh and reauthorization from committing conflicting upstream credentials. A busy refresh rejects exchange before sending the authorization code. An abandoned exchange reservation is treated conservatively as requiring fresh authorization.
+
+Notion authorization identity includes workspace, bot and authorizing user. From the [2026-06-08 change](https://developers.notion.com/page/changelog#june-8-2026), newly created Public Connections issue a new token pair per OAuth authorization, while existing connections retain previous token behavior. The SDK stores the returned pair and does not assume every authorization is either shared or independent. Pagination cursors are bounded opaque strings, not parsed UUIDs.
+
+Deletion persists a tombstone before cleanup, and authorization epochs prevent old in-flight callbacks from reviving connections. Workers check lease, owner/connection state and generation around external execution. Cancellation cannot retract a request already sent to the upstream service; results remain fenced locally and durable cleanup is retained as necessary.
+
+Provider documentation reviewed during implementation:
+
+- [Google OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect)
+- [Apple verification](https://developer.apple.com/documentation/signinwithapple/verifying-a-user) and [token exchange](https://developer.apple.com/documentation/signinwithapplerestapi/generate-and-validate-tokens)
+- [GitHub OAuth](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps) and [email API](https://docs.github.com/en/rest/users/emails)
+- [Notion authorization](https://developers.notion.com/guides/get-started/authorization), [refresh](https://developers.notion.com/reference/refresh-a-token), [revocation](https://developers.notion.com/reference/revoke-token)
+- [Raindrop authorization](https://developer.raindrop.io/v1/authentication/token), [collections](https://developer.raindrop.io/v1/collections/methods), [bookmarks](https://developer.raindrop.io/v1/raindrops/single)
+- [OAuth security BCP](https://www.rfc-editor.org/rfc/rfc9700.html) and [native applications](https://www.rfc-editor.org/rfc/rfc8252.html)
+
+Provider versions are configurable and product-owned. Changing a default in the SDK does not change a product's deliberately pinned protocol version.

package/docs/verification.md

@@ -0,0 +1,22 @@
+# Local verification — 2026-10-31
+
+This is implementation acceptance, not a production release or real-provider acceptance.
+
+## SDK
+
+- TypeScript strict typecheck passed.
+- 77 unit/protocol/state-machine tests passed on Node.js 24.14.0 and 22.12.0.
+- Six PostgreSQL integration tests passed on a dedicated local `integration_sdk_test` database: atomic callback consumption, host transaction rollback, concurrent idempotency/claim, crash recovery, revocation pagination fences and atomic result projection.
+- Two packed ESM/CommonJS tests passed using the real npm tarball, including provider/core errors across independently bundled entries.
+- An independent product fixture installed the tarball, generated its own Prisma 6.13 client and passed real-Prisma authorization, transaction rollback, durable execution and result projection. Its provider responses are simulated; no real third-party grant was created.
+- The package contains compiled entries, declarations, schema/migration, examples and documentation. Runtime dependencies do not include either product or their source checkouts.
+
+Commands: `pnpm check`; `npx --yes --package=node@22.12.0 -- node node_modules/vitest/vitest.mjs run`; `SDK_TEST_DATABASE_URL=... pnpm test:integration`; `SDK_PACKAGE_ARCHIVE=... pnpm exec vitest run test/providers.package.test.ts`; `SDK_TEST_DATABASE_URL=... node scripts/verify-package.mjs`.
+
+## Product consumers
+
+Subtic retains its existing grant, refresh, task and subscription state; only the Notion/Raindrop provider protocol path consumes the SDK in this initial adoption. Its initial verification passed 51 provider/API unit contracts and 27 isolated-database tests, connector typechecks/lint and API/Worker builds. See its `docs/account-integrations/sdk-adoption.md` for the final consumer artifact record.
+
+Kiipu adds the new embedded runtime, separate product-local configuration, provider login adapters and Notion/Raindrop UI/API/Worker paths. Its initial verification passed the current-source unit suite, application typechecks/builds, isolated Prisma/Redis host contracts and fixture-backed browser interactions. See its `docs/integrations-sdk.md` for the final consumer commands and counts.
+
+All database changes made during acceptance were restricted to isolated local test databases; no existing development or production database was migrated. No Git commit/push, npm publication or deployment was performed. Real OAuth console configuration, consent, remote writes/revocation behavior and native-device acceptance remain release work.

package/examples/embedded-host.ts

@@ -0,0 +1,62 @@
+import {
+  createIntegrationSdk,
+  createTokenVault,
+  createRuntime,
+  type HostHooks,
+} from "@mycreat-labs/integrations-sdk";
+import {
+  createNotionProvider,
+  createRaindropProvider,
+} from "@mycreat-labs/integrations-sdk/providers";
+import {
+  createPrismaStore,
+  bindPrismaTransaction,
+  type PrismaClientLike,
+  type PrismaTransactionLike,
+} from "@mycreat-labs/integrations-sdk/prisma";
+import { createBullMqTransport } from "@mycreat-labs/integrations-sdk/bullmq";
+import { createRedisRateLimiter } from "@mycreat-labs/integrations-sdk/redis";
+import type Redis from "ioredis";
+
+// The application supplies its own configuration, infrastructure and business checks.
+export function embeddedHost(
+  database: PrismaClientLike,
+  redis: Redis,
+  config: {
+    namespace: string;
+    keyId: string;
+    keys: Record<string, string>;
+    notion: Parameters<typeof createNotionProvider>[0];
+    raindrop: Parameters<typeof createRaindropProvider>[0];
+  },
+  hooks: HostHooks,
+) {
+  const sdk = createIntegrationSdk({
+    namespace: config.namespace,
+    store: createPrismaStore(database),
+    vault: createTokenVault({ activeKeyId: config.keyId, keys: config.keys }),
+    providers: [
+      createNotionProvider(config.notion),
+      createRaindropProvider(config.raindrop),
+    ],
+    hooks,
+    rateLimiter: createRedisRateLimiter(redis, {
+      prefix: config.namespace,
+      limit: 3,
+      windowMs: 1000,
+    }),
+  });
+  const runtime = createRuntime({
+    sdk,
+    queue: createBullMqTransport({
+      connection: redis,
+      prefix: config.namespace,
+    }),
+  });
+  return {
+    sdk,
+    runtime,
+    transaction: (tx: PrismaTransactionLike) =>
+      sdk.withStore(bindPrismaTransaction(tx)),
+  };
+}

package/migrations/0001_initial.sql

@@ -0,0 +1,40 @@
+CREATE TABLE integration_sdk_meta (id INTEGER PRIMARY KEY, version INTEGER NOT NULL);
+INSERT INTO integration_sdk_meta (id,version) VALUES (1,1);
+CREATE TABLE integration_sdk_owners (
+  namespace TEXT NOT NULL, owner_id TEXT NOT NULL, erased BOOLEAN NOT NULL DEFAULT false,
+  epochs JSONB NOT NULL DEFAULT '{}',
+  CONSTRAINT integration_sdk_owners_pkey PRIMARY KEY (namespace,owner_id)
+);
+CREATE TABLE integration_sdk_flows (
+  namespace TEXT NOT NULL, id TEXT NOT NULL, owner_id TEXT NOT NULL, purpose TEXT NOT NULL,
+  binding_hash TEXT NOT NULL, expires_at BIGINT NOT NULL, data JSONB NOT NULL,
+  CONSTRAINT integration_sdk_flows_pkey PRIMARY KEY (namespace,id)
+);
+CREATE INDEX integration_sdk_flows_expiry_idx ON integration_sdk_flows (expires_at);
+CREATE TABLE integration_sdk_grants (
+  namespace TEXT NOT NULL, id TEXT NOT NULL, owner_id TEXT NOT NULL, version INTEGER NOT NULL, data JSONB NOT NULL,
+  CONSTRAINT integration_sdk_grants_pkey PRIMARY KEY (namespace,id)
+);
+CREATE INDEX integration_sdk_grants_owner_idx ON integration_sdk_grants (namespace,owner_id);
+CREATE TABLE integration_sdk_connections (
+  namespace TEXT NOT NULL, id TEXT NOT NULL, owner_id TEXT NOT NULL, provider TEXT NOT NULL,
+  registration_id TEXT NOT NULL, account_id TEXT NOT NULL, generation INTEGER NOT NULL, data JSONB NOT NULL,
+  CONSTRAINT integration_sdk_connections_pkey PRIMARY KEY (namespace,id),
+  CONSTRAINT integration_sdk_connections_account_key UNIQUE (namespace,owner_id,provider,registration_id,account_id)
+);
+CREATE UNIQUE INDEX integration_sdk_connections_account_owner_key ON integration_sdk_connections (namespace,provider,registration_id,account_id);
+CREATE TABLE integration_sdk_operations (
+  namespace TEXT NOT NULL, id TEXT NOT NULL, owner_id TEXT NOT NULL, connection_id TEXT NOT NULL,
+  action TEXT NOT NULL, idempotency_key TEXT NOT NULL, version INTEGER NOT NULL, status TEXT NOT NULL,
+  available_at BIGINT NOT NULL, lease_until BIGINT, data JSONB NOT NULL,
+  CONSTRAINT integration_sdk_operations_pkey PRIMARY KEY (namespace,id),
+  CONSTRAINT integration_sdk_operations_idempotency_key UNIQUE (namespace,owner_id,action,idempotency_key)
+);
+CREATE INDEX integration_sdk_operations_due_idx ON integration_sdk_operations (namespace,status,available_at);
+CREATE INDEX integration_sdk_operations_owner_idx ON integration_sdk_operations (namespace,owner_id);
+CREATE TABLE integration_sdk_events (
+  namespace TEXT NOT NULL, id TEXT NOT NULL, owner_id TEXT NOT NULL, operation_id TEXT NOT NULL,
+  created_at BIGINT NOT NULL, data JSONB NOT NULL,
+  CONSTRAINT integration_sdk_events_pkey PRIMARY KEY (namespace,id)
+);
+CREATE INDEX integration_sdk_events_owner_idx ON integration_sdk_events (namespace,owner_id,created_at,id);

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "@mycreat-labs/integrations-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Product-embedded third-party identity and integration runtime",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "migrations",
+    "schema.prisma",
+    "README.md",
+    "CHANGELOG.md",
+    "docs",
+    "examples"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "packageManager": "pnpm@10.14.0",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./providers": {
+      "types": "./dist/providers/index.d.ts",
+      "import": "./dist/providers/index.js",
+      "require": "./dist/providers/index.cjs"
+    },
+    "./postgres": {
+      "types": "./dist/adapters/postgres.d.ts",
+      "import": "./dist/adapters/postgres.js",
+      "require": "./dist/adapters/postgres.cjs"
+    },
+    "./prisma": {
+      "types": "./dist/adapters/prisma.d.ts",
+      "import": "./dist/adapters/prisma.js",
+      "require": "./dist/adapters/prisma.cjs"
+    },
+    "./redis": {
+      "types": "./dist/adapters/redis.d.ts",
+      "import": "./dist/adapters/redis.js",
+      "require": "./dist/adapters/redis.cjs"
+    },
+    "./bullmq": {
+      "types": "./dist/adapters/bullmq.d.ts",
+      "import": "./dist/adapters/bullmq.js",
+      "require": "./dist/adapters/bullmq.cjs"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "check": "pnpm typecheck && pnpm test && pnpm build"
+  },
+  "dependencies": {
+    "jose": "^6.1.0"
+  },
+  "peerDependencies": {
+    "bullmq": ">=5.58.0 <6",
+    "ioredis": ">=5.7.0 <6"
+  },
+  "peerDependenciesMeta": {
+    "bullmq": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "bullmq": "^5.58.0",
+    "ioredis": "^5.7.0",
+    "pg": "^8.16.3",
+    "@types/pg": "^8.15.5",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/schema.prisma

@@ -0,0 +1,80 @@
+// Copy these models into the host schema and apply migrations/0001_initial.sql through
+// the host's migration pipeline. SDK SQL does not import generated Prisma models.
+model IntegrationSdkMeta {
+  id Int @id
+  version Int
+  @@map("integration_sdk_meta")
+}
+model IntegrationSdkOwner {
+  namespace String
+  ownerId String @map("owner_id")
+  erased Boolean @default(false)
+  epochs Json @default("{}")
+  @@id([namespace,ownerId], map: "integration_sdk_owners_pkey")
+  @@map("integration_sdk_owners")
+}
+model IntegrationSdkFlow {
+  namespace String
+  id String
+  ownerId String @map("owner_id")
+  purpose String
+  bindingHash String @map("binding_hash")
+  expiresAt BigInt @map("expires_at")
+  data Json
+  @@id([namespace,id], map: "integration_sdk_flows_pkey")
+  @@index([expiresAt], map: "integration_sdk_flows_expiry_idx")
+  @@map("integration_sdk_flows")
+}
+model IntegrationSdkGrant {
+  namespace String
+  id String
+  ownerId String @map("owner_id")
+  version Int
+  data Json
+  @@id([namespace,id], map: "integration_sdk_grants_pkey")
+  @@index([namespace,ownerId], map: "integration_sdk_grants_owner_idx")
+  @@map("integration_sdk_grants")
+}
+model IntegrationSdkConnection {
+  namespace String
+  id String
+  ownerId String @map("owner_id")
+  provider String
+  registrationId String @map("registration_id")
+  accountId String @map("account_id")
+  generation Int
+  data Json
+  @@id([namespace,id], map: "integration_sdk_connections_pkey")
+  @@unique([namespace,ownerId,provider,registrationId,accountId], map: "integration_sdk_connections_account_key")
+  @@unique([namespace,provider,registrationId,accountId], map: "integration_sdk_connections_account_owner_key")
+  @@map("integration_sdk_connections")
+}
+model IntegrationSdkOperation {
+  namespace String
+  id String
+  ownerId String @map("owner_id")
+  connectionId String @map("connection_id")
+  action String
+  idempotencyKey String @map("idempotency_key")
+  version Int
+  status String
+  availableAt BigInt @map("available_at")
+  leaseUntil BigInt? @map("lease_until")
+  data Json
+  @@id([namespace,id], map: "integration_sdk_operations_pkey")
+  @@unique([namespace,ownerId,action,idempotencyKey], map: "integration_sdk_operations_idempotency_key")
+  @@index([namespace,status,availableAt], map: "integration_sdk_operations_due_idx")
+  @@index([namespace,ownerId], map: "integration_sdk_operations_owner_idx")
+  @@map("integration_sdk_operations")
+}
+model IntegrationSdkEvent {
+  namespace String
+  id String
+  ownerId String @map("owner_id")
+  operationId String @map("operation_id")
+  createdAt BigInt @map("created_at")
+  data Json
+  @@id([namespace,id], map: "integration_sdk_events_pkey")
+  @@index([namespace,ownerId,createdAt,id], map: "integration_sdk_events_owner_idx")
+  @@map("integration_sdk_events")
+}