Connectors

From npm-packages/connectors/README.md in the Bijection source.

Bijection connectors

Declare typed external resources with dataset.table, pubsub.subscription, kubernetes.pods and the other exported provider constructors. Install them in bijection.bindings.ts, expose their rows with defineSyncedTable({ source: resource }) and read them through ordinary queries. The SDK owns resource identity and binding types; native acquisition, credentials, commands and publication retain their enforcement.

File selection

S3, Drive and Dropbox accept a bounded select predicate in copy, reference, folder and writable modes. Listing and change cursors belong to the private native inventory. Selection changes public membership and current byte access; it neither invents a provider deletion nor stops inventory reconciliation.

Copy codeexport const invoices = s3.bucket({
  content: { kind: "copy" },
  select: { all: [
    { field: "relativePath", test: "matches", pattern: "invoices/[^/]+\\.pdf" },
    { field: "sizeBytes", test: "between", maximum: "8388608" },
    { field: "modifiedAt", test: "atOrAfter", value: "2026-01-01T00:00:00Z" },
  ] },
});

Use all, any and not; missing metadata remains unresolved even under negation. Text predicates use equals or full-string matches with the native linear-time regular-expression grammar. Native validation refuses unsupported syntax. Limits are 8 KiB, 64 predicates, 8 levels, 16 children per group and 1024 bytes per text value. Size bounds are canonical unsigned decimal strings, preserving integers larger than JavaScript's exact range; dates require RFC3339.

Unsupported fields refuse at authoring. A sound selected size ceiling narrows native copy capacity; any needs a ceiling on every arm. Metadata page bounds, content obligations and download byte limits remain independent of population selection. Copy content.maxBytes is 1 byte–1 GiB, default 256 MiB; larger originals use Media's existing acquisition handoff on customer compute. No configurable turn budget is claimed beyond the native scheduler's enforced work allowances.

bijection source files <source> [key] shows a bounded retained-inventory preview, predicate/ancestry reasons, exact content readiness and the installed write commands. Continue with --after <key>. Each page has its current observed basis; it is neither a live provider listing nor a multi-page snapshot. S3 and Dropbox support conditional replacement/deletion; Drive exposes attributable resumable creation only. Application policy remains mandatory; provider ACLs are not imported.

mqtt.telemetry and pubsub.telemetry interpret a JSON record once for its raw archive, typed history, native series and latest state. The resource exposes the latest collection through the ordinary synced-table API:

Copy codeconst tanks = mqtt.telemetry.latest({
  identity: ["eventId"],
  record: {
    encoding: "json",
    schema: {
      eventId: v.string(),
      tankId: v.string(),
      at: v.int64(),
      temperature: v.number(),
    },
    time: { field: "at", unit: "milliseconds" },
  },
  archive: true,
  history: true,
  series: { table: "temperatures", key: "tankId", orderBy: "at" },
  latest: { key: ["tankId"], publishEvery: { seconds: 2 } },
});

Declare temperatures with defineSeries and bind the resource's latest state with defineSyncedTable({ source: tanks }). Physical topics, subscription names, credentials and dataset placement belong to deployment bindings. MQTT's identity selects the publisher's occurrence ID, independently of the tank key and business ordering. The low-level defineIntegration event contract also supports histories and series without a latest collection, and MQTT or Pub/Sub commands with explicit acknowledgement correlation.

Single resources expose one table through defineSyncedTable({ source: resource }). Coupled resources such as postgres.database, imap.mailbox, gmail.mailbox and microsoftGraph.folder expose resource.tables.<name>. Declare every member; there is no primary table in a group. One group has one acquisition owner.

Provider implementations live in src/providers. They include the PostgreSQL and IMAP factories, Gmail and Graph readers, Stripe customer acquisition, Google Calendar and provider listener recipes. Mail and Stripe billing compose this catalog. Protocol primitives and lowering belong to bijection/connectors in the SDK; generic HTTP builders belong to component-support.

Deployment bindings supply setup, a private credential reference, and optional acquisition: { every: { seconds: 30 } }. Each provider's credential(name) names that provider's own credential kind, so a Stripe credential cannot bind a Gmail mailbox; generic HTTP resources share the http kind. Cadence is deployment policy, separate from provider settings. Native binding status reports admitted per-collection capabilities; a provider name does not establish hosted qualification.

Entry points

Packaged connectors have their own entry points, so an application imports only the provider it installs:

Copy codeimport { googleCalendar } from "@bijectionhq/connectors/google-calendar";
import { stripe } from "@bijectionhq/connectors/stripe";
import { stripeWebhook } from "@bijectionhq/connectors/webhooks";
import { postgres } from "@bijectionhq/connectors/postgres";
import { http } from "@bijectionhq/connectors/http";

The root entry point keeps every provider constructor. The package requires a Bijection SDK in the >=0.1.5 <0.2.0 range as a peer; its exact source revision, source digest and assembled workspace digest are the platform's import lock.

Connector metadata and catalog

Each packaged connector lives in src/connectors/<id>/ with its entry point (index.ts), documentation (README.md), scenario module (scenarios.ts) and retained fixtures. index.ts exports metadata from defineConnector: id, title, entry point, owner, resource constructors and package-relative documentation and scenario paths. Metadata states no capability and no qualification. Acquisition, deletion, recovery, command guarantees and enforced limits are read from the admitted declaration and its native source profile; evidence is tied to exact source and runtime identities.

Generate catalog.json, contract-analysis.json, evidence.json and docs.bundle.json together with src/catalog/tool.ts --run-fixtures. Use --native-analysis <file> for the shared build core's complete admission bundle; an absent bundle leaves native capability analysis explicitly unavailable. --check refuses stale generated artifacts and examples. The catalog test also checks registration parity.

Inspect an installed package offline with bijection connector list and bijection connector inspect <case-id> --format json. --package <directory> selects an explicit installation. Inspection does not contact a provider.

The documentation bundle exposes four independent verification categories: packageFixtures, nativeContracts, deployedProvider and distributedPackage. Each is notRun, unavailable, or recorded with its outcome, applicable artifact/configuration, receipt identities and executed-case counts. Native capability analysis is separate from native test execution. A digest establishes content identity, not trust in the producer.

Release tooling imports VerificationInput from @bijectionhq/connectors/catalog through --verification <private-input.json>. Feed this only artifacts retained by the trusted build or qualification owner. A receipt binds the declaration, connector/runtime/adapter artifacts, configuration, provider version or installed archive, suite, fault conditions, assertions, retained evidence and cleanup owner. Real-provider and controlled-provider runs are distinguished. Missing cases, zero-assertion passes, changed output digests and unfinished cleanup cannot count as a complete pass. Optional performance measurements retain their workload. Run timestamps use explicit UTC (Z) with optional millisecond precision, so expiry has the same meaning on every build host. Raw provider/log artifacts and deployment addresses stay with the private run; public output retains digests and scoped assertions. The CLI reevaluates expiry at inspection time. No receipt changes live source coverage or grants authority.

Hosted qualification is opt-in. Adding a receipt schema or test reference does not establish an operating envelope or a distributed-package pass.

Workflow requirements

assessWorkflow from @bijectionhq/connectors/catalog compares a selected case's native profile with an application's acquisition and capacity requirements. Pass the generated catalog, exact native analyses, current connector and analyzer artifacts, and check receipts with their selected runtime/check artifacts. It uses the catalog's existing receipt validation and grants no execution authority.

Copy codeconst requirement = {
  collections: {
    records: {
      initial: ["pinned_snapshot"],
      deletions: ["explicit_events", "reconciliation"],
      minimumRetentionMs: "21600000",
      minimumLimits: { http_response_bytes: "262144" },
    },
  },
  checks: [
    {
      scenario_id: "page-publication-recovery",
      target: { kind: "collection", name: "records" },
    },
  ],
};

The result keeps contract, findings, checks, evidence, restrictions and qualification separate. Unknown capacity or retention is unknown, never unlimited. Decimal comparisons preserve integers above JavaScript's safe-number range. An enforced upper bound is not a throughput benchmark or proof that a provider accepts the workload. Package and native checks retain independent references; a newer failure cannot be hidden by an older pass or a different check. These receipts never establish hosted qualification.

Validation workflow

A connector supplies declarations, retained fixtures and scenario references; @bijectionhq/connectors/validation supplies the execution and reporting. requiredScenarios(subject) derives the applicable scenarios from the subject's admitted contract: identity, discovery, stated-cursor or last-key continuation, incremental token resets, change-history gaps, page publication recovery, push listener deduplication and custody, uncertain command responses, backoff and shared budgets. A feature the connector does not declare requires no scenario.

Each scenario reference is one of:

• package: a JSON fixture replayed by runPackageFixture through the declaration's own invokeIntegration and request syscall, exactly as the native host selects the handler. It checks parsing, mapping and refusals.
• native: an existing engine history (crate, test target, test) that exercises admission, persistence, recovery, publication and authority.
• unestablished: the scenario applies and no check exercises it yet, with the reason. It is reported and never counted as passing.

The catalog test requires a reference for every applicable scenario and runs every package fixture. The platform's component-contract checks verify that native references name existing tests. Hosted qualification against a real provider remains a separate, explicitly requested Atlas run.

Authoring HTTP connectors

defineResource declares the complete setup once; http.connection({ fields }) names the connection-owned subset, and selection names the field that selects one resource on the connection. Connections may declare discover, budget and backoff. http.records maps resource fields to nested provider item paths with fields, declares cursor pagination with an explicit terminal and refuses a repeated cursor. http.exchange lowers a command over the provider's own receipts.

Captured gRPC services

@bijectionhq/connectors/grpc composes generated grpc.service methods with defineResource. grpc.connection declares an explicit account/incarnation identity RPC. grpc.records declares list items, opaque continuation, field mapping and optional point refresh. Listing endings establish no absence; non-successful point RPCs remain unresolved.

Generated methods construct native request/response contracts and message validators. They open no sockets and import no provider client. Commands compose those methods through command, with explicit governing rules, target versions, original operation IDs, provider deduplication retention and read-only receipt lookup. A transport status alone establishes no business outcome.

The first profile supports bounded unary proto3 over TLS/mTLS. Signed int64 values use bigint, uint64 uses decimal text, bytes use ArrayBuffer, maps use entry arrays and oneof uses optional tagged unions. Streaming, recursion, compression and dynamic Any/Struct representations are unsupported. The platform's examples/grpc-inventory supplies a complete application and a Go provider with durable original-request receipts and lost-response injection.

File resources

S3, Google Drive, Dropbox and Microsoft Graph Drive expose independent items, contents and versions tables. Declare and install each role. Metadata paging advances after the same transaction has accepted its content obligations; file transfers run independently. versions appends the exact acquired representation with its provider version, native file reference, digest, acquisition time and expiry. It retains observed copies for 30 days by default. Set history: { mode: "observed", retainFor: { days: 7 } } for a different finite retention, from 1 to 365 days. This records versions Bijection actually acquired; provider revisions missed between observations are not reconstructed.

Google Drive's explicit export constructor adds an exports table and retains original and exported representations in the same versions role. Reference resources expose items only. File storage references require the application's read policy. A history row does not grant access to the provider or its bytes.

Use googleDrive.drive.folders({ folderIds: ["stable-folder-id"] }) for binary copies under selected folders, googleDrive.drive.folderReferences(...) for metadata references, and googleDrive.drive.folderExporting({ folderIds, exportMimeType }) for an explicit Workspace export. microsoftGraph.drive.folders({ folderIds }) selects folders in one drive. The roots are distinct stable provider IDs, at most sixteen; resolve provider aliases such as root before declaring them. Graph's folder profile currently exposes acquisition only.

These profiles acquire metadata once into a private inventory and expose only current selected membership through items. The private inventory has no application table or Dataset binding. Define an explicit application read policy on the public metadata table. Native point reads and retained file reads recheck the current parent chain, so an observed folder withdrawal or move fences descendants before bounded local reconciliation finishes. Missing parents, ambiguous ancestry and cycles establish no inclusion. Range reads wait while their membership frontier is unsettled. The existing source refresh and pause controls address the private inventory's acquisition schedule. Changes to selected roots rescan retained metadata and refresh newly included content without starting another provider listing.

Deployment file acquisition separates work from membership. For example, bind(files, { setup, credential, acquisition: { every: { minutes: 5 }, budget: { metadataPagesPerTurn: 8, contentBytesPerTurn: "536870912" } } }) caps each native turn without narrowing the selected file population. Pages are bounded by the native eight-page fairness limit (file listings currently use one page per turn). Native copies acquire whole responses, so contentBytesPerTurn must admit at least the declared content.maxBytes; admission refuses a smaller allowance instead of permanently starving a large file. The native content backlog selects a bounded prefix and preserves every remaining key, cursor and generation. External range acquisition retains its own Pipeline work budget.