# @x12i/memorix-connector-sdk

> Memorix Connector SDK — defineConnector, workflow, checkpoint-aware collectStream, host/remote/testing surfaces, and conformance utilities.

Latest version **1.3.0** (published 2026-08-05) · exellix-license license · 0 weekly downloads

## Install

```sh
npm install @x12i/memorix-connector-sdk
pnpm add @x12i/memorix-connector-sdk
yarn add @x12i/memorix-connector-sdk
bun add @x12i/memorix-connector-sdk
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.3.0 |
| Published | 2026-08-05 |
| First published | 2026-07-30 |
| Weekly downloads | 0 |
| License | exellix-license |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 2 |
| Unpacked size | 198.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |
| Keywords | x12i, memorix, connector, sdk |

## Links

- npm: https://www.npmjs.com/package/@x12i/memorix-connector-sdk
- Repository: https://github.com/x12i/memorix-mono-repo
- Homepage: https://github.com/x12i/memorix-mono-repo#readme
- Issues: https://github.com/x12i/memorix-mono-repo/issues
- npm.io page: https://npm.io/package/@x12i/memorix-connector-sdk

## Dependencies (2)

- [@x12i/credorix-core](https://npm.io/package/@x12i/credorix-core.md) ^1.3.1
- [@x12i/memorix-metadata](https://npm.io/package/@x12i/memorix-metadata.md) ^3.0.3

## Recent versions

- 1.3.0 (latest) — 2026-08-05
- 1.2.0 — 2026-08-02
- 1.1.1 — 2026-07-30
- 1.1.0 — 2026-07-30

## README

# `@x12i/memorix-connector-sdk` — Memorix Connector Framework

**One connector contract for source workflows, checkpoints, raw persistence, and reusable data.**

```bash
npm install @x12i/memorix-connector-sdk@^1.1.1
```

Package surfaces:

| Export | Purpose |
|--------|---------|
| `@x12i/memorix-connector-sdk` | Authoring: `defineConnector`, workflow, `collectStream`, types, Credorix adapters |
| `.../host` | In-process host, staged content (no stub HTTP — use Credorix or testing port) |
| `.../remote` | `createRemoteCommitPagePort`, remote host client |
| `.../testing` | Conformance ports, fixtures, APS session helpers (`startApsSession`) |
| (removed) | Use defineConnector only — no MemoryConnector wrap |

Connectors own provider-specific API choreography. Memorix owns checkpoints, exact raw persistence, deduplication, quarantine, and durable results. This SDK has **no Mongo dependency**.

## Simulation (Studio + APS)

Set `capabilities.simulation: true` when the connector can run against an **`@x12i/api-simulator`** `baseUrl` with the same pull code (MX-CF-FR-019). Studio toggles mode via `x-memorix-simulation`.

- Cert: `startApsSession` / named `cf.*` scenarios (`./testing`)
- Studio domain sims: pack-shipped package-sim scenarios (APS-CF-FR-009…012) — **not** a private mock server
- Unit-only `mock-provider` in refs stays for fast unit tests; do not expand it into Studio simulation

See `docs/connector-framework/MX-CF-simulation-requirements.md` and tutorial `add-aps-simulation-to-service`.

## Quick start

```ts
import {
  defineConnector,
  defineWorkflow,
  defineStreamTemplates,
  commandStep,
  pollStep,
  collectStep,
} from "@x12i/memorix-connector-sdk";

const streams = defineStreamTemplates([
  {
    streamId: "results",
    objectType: "provider-result",
    dataCategory: "entity",
    identity: { kind: "path", path: "id" },
    checkpoint: { method: "cursor", strategyVersion: 1 },
  },
]);

const workflow = defineWorkflow({
  id: "default",
  version: 1,
  steps: [
    commandStep({ id: "start-export", title: "Prepare export" }),
    pollStep({ id: "wait-for-export", dependsOn: ["start-export"] }),
    collectStep({ id: "collect-results", streamId: "results", dependsOn: ["wait-for-export"] }),
  ],
});

export default defineConnector({
  id: "provider-connector",
  version: "1.0.0",
  capabilities: { pull: true, cursor: true },
  streams,
  workflow,
  async pull(ctx) {
    await ctx.workflow.run(workflow, {
      handlers: {
        "start-export": async () => provider.startExport(await ctx.credentials.resolve()),
        "wait-for-export": async () => provider.waitReady(),
        "collect-results": async () =>
          ctx.collectStream({
            streamId: "results",
            fetchPage: async ({ checkpoint, pageToken, signal }) => {
              const page = await provider.fetchResults({ checkpoint, pageToken, signal });
              return {
                items: page.items.map((i) => ({ data: i, identity: i.id })),
                nextCheckpoint: { method: "cursor", value: page.nextCursor },
                complete: !page.nextCursor,
              };
            },
          }),
      },
    });
  },
});
```

## Must

- Use `ctx.workflow.run` + `ctx.collectStream` for collection
- Return exact provider-native payloads
- Resolve secrets only via `ctx.credentials` / `ctx.http` (Credorix-backed in production)
- Honor host budget, abort signal, and page size

## Must not

- Advance checkpoints without a successful page land
- Access Mongo, global `fetch`, or raw secret files
- Call `capability.request()` — `brokered-fetch` is descriptor-only; use `ctx.http`
- Promote / rename into business models
- Ask operators to run workflow steps individually

## Credentials & HTTP

- Production: host mints Credorix delegation (`@x12i/credorix-client@^1.3.0`) and adapts ports via `adaptGovernedHttpPort`
- Purposes: `provider-http | provider-sign | webhook-verification | material-lease` (legacy `provider-request` → `provider-http`)
- Testing: `@x12i/memorix-connector-sdk/testing` → `startApsSession` / `assertApsEvidence` against `@x12i/api-simulator@^1.2.0`

## Protocol

- Version: `memorix-connector/1`
- Unsupported majors → `CONNECTOR_PROTOCOL_UNSUPPORTED`

## Related

- Docs: `docs/connector-framework/`
- `@x12i/credorix-client` / `@x12i/credorix-core` — governed credentials + egress
- `@x12i/api-simulator` — certification scenarios
- `@x12i/memorix-client` — remote commit/checkpoint APIs
- `@x12i/memorix-memory` — in-process collector + `native DefinedConnector`

---
_Source: https://npm.io/package/@x12i/memorix-connector-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._