@x12i/memorix-connector-sdk

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

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

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

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