@useairfoil/connector-kit 0.4.0 → 0.5.0

package/README.md

@@ -1,123 +1,316 @@
 # @useairfoil/connector-kit
 
-Toolkit for building Airfoil connectors with Effect.
+Toolkit for building Airfoil producer connectors with Effect.
 
----
+`@useairfoil/connector-kit` gives connector authors the pieces needed to define, run, test, and publish resource-first producer connectors:
 
-## User guide (build a connector)
+- `Connector.define(...)` describes a connector.
+- `Resource.entity(...)` describes a Wings table-backed resource.
+- `Fetch.page(...)` and `Fetch.changes(...)` describe backfill and polling fetches.
+- `Resource.webhook(...)` lets a resource normalize provider webhook payloads into mutations.
+- `Webhook.route(...)` defines connector-level HTTP webhook routes.
+- `Ingestion.run(...)` runs resource ingestion and checkpoints after accepted publishes.
+- `Publisher.layerConsole` logs accepted batches locally.
+- `Publisher.layerWings(...)` publishes resource mutations into Wings tables.
+- `ConnectorApp.start(...)` starts a complete Node HTTP connector process.
 
-This section is for connector authors who want to build and run a connector.
+The package is intentionally Layer-oriented: connector code defines resources and routes, while entrypoints provide runtime dependencies such as publishers, state stores, telemetry, and API clients.
 
-### Install
+## Install
 
 ```bash
-bun add @useairfoil/connector-kit
+pnpm add @useairfoil/connector-kit effect@beta
 ```
 
-### Minimal example
+This repo currently uses Effect v4 beta. In workspace packages, prefer the workspace catalog (`"effect": "catalog:"`) so all packages stay on the pinned beta version.
+
+## Package Shape
+
+The package root exposes the common connector authoring API:
 
 ```ts
-import { Schema, Effect, Layer, Stream } from "effect";
 import {
-  defineConnector,
-  defineEntity,
+  Connector,
+  ConnectorApp,
+  ConnectorError,
+  Cursor,
+  Fetch,
+  Ingestion,
   Publisher,
-  runConnector,
-  StateStoreInMemory,
-  WebhookServerLayer,
-  makeWebhookQueue,
+  Resource,
+  StateStore,
+  Telemetry,
+  Webhook,
 } from "@useairfoil/connector-kit";
+```
+
+Subpath exports are available for runtime domains:
+
+- `@useairfoil/connector-kit/ingestion`
+- `@useairfoil/connector-kit/connector-app`
+- `@useairfoil/connector-kit/publisher`
+- `@useairfoil/connector-kit/state-store`
+- `@useairfoil/connector-kit/webhook`
+- `@useairfoil/connector-kit/errors`
+
+Core definition helpers and `Telemetry` are intentionally root-only.
+
+## Resource Model
+
+Resources emit mutations, not raw rows. Connector Kit currently supports `Resource.entity(...)` for Wings table-backed resources.
+
+```ts
+const Posts = Resource.entity({
+  name: "posts",
+  schema: PostSchema,
+  key: "id",
+  version: "updatedAt",
+  backfill: Fetch.page({
+    pageCursor: Cursor.number(),
+    cutoff: Cursor.isoDateTime(),
+    fetch: ({ pageCursor }) =>
+      api.fetchPosts({ page: typeof pageCursor === "number" ? pageCursor : 1 }).pipe(
+        Effect.map((page) => ({
+          mutations: page.items.map(Resource.upsert),
+          nextPageCursor: page.hasMore ? page.nextPage : page.page,
+          hasMore: page.hasMore,
+        })),
+      ),
+  }),
+});
+```
+
+`key` and `version` autocomplete from the decoded schema row type. Invalid field names are rejected at compile time.
+
+Mutations are created with:
+
+```ts
+Resource.upsert(row);
 
-const Customer = Schema.Struct({
-  id: Schema.String,
-  email: Schema.String,
-  created_at: Schema.Date,
+Resource.delete({
+  key: "post_123",
+  version: "2026-01-01T00:00:00.000Z",
 });
+```
 
-const program = Effect.gen(function* () {
-  const webhook = yield* makeWebhookQueue<Schema.Schema.Type<typeof Customer>>();
-
-  const connector = defineConnector({
-    name: "producer-example",
-    entities: [
-      defineEntity({
-        name: "customers",
-        schema: Customer,
-        primaryKey: "id",
-        live: webhook.queue,
-        backfill: Stream.empty,
-      }),
-    ],
-    events: [],
-  });
-
-  yield* runConnector(connector, new Date());
-}).pipe(
-  Effect.provide(StateStoreInMemory),
-  Effect.provide(
-    Layer.succeed(Publisher, {
-      publish: () => Effect.succeed({ requestId: 1n }),
-    }),
-  ),
-  Effect.provide(
-    WebhookServerLayer({
-      port: 8080,
-      routes: [
-        {
-          path: "/webhook/customers",
-          schema: Customer,
-          dispatch: (payload) =>
-            Effect.succeed([
-              {
-                queue: webhook.queue,
-                batch: { cursor: new Date(), rows: [payload] },
-              },
-            ]),
-        },
-      ],
+## Fetches
+
+`Fetch.page(...)` is for paginated backfill. It receives the stored page cursor and the resource cutoff.
+
+`Fetch.changes(...)` is for polling incremental changes. It receives the stored changes cursor and can be configured with an interval.
+
+Cursor helpers:
+
+- `Cursor.string()`
+- `Cursor.number()`
+- `Cursor.isoDateTime()`
+- `Cursor.nowIsoDateTime`
+
+Date cursor values are accepted at API boundaries and normalized to ISO strings before checkpoint writes.
+
+## Webhooks
+
+Webhooks are connector-level routes with schema-validated payloads. A route dispatches to resource-owned webhook handlers by calling `to(resource, payload)`.
+
+```ts
+const Posts = Resource.entity({
+  name: "posts",
+  schema: PostSchema,
+  key: "id",
+  version: "updatedAt",
+  webhook: Resource.webhook({
+    schema: PostEventSchema,
+    handler: ({ payload }) => Effect.succeed([Resource.upsert(payload.data)]),
+  }),
+});
+
+const route = Webhook.route({
+  path: "/webhooks/example",
+  ackMode: "after-publish",
+  schema: ProviderWebhookSchema,
+  handler: ({ request, rawBody, payload, to }) =>
+    Effect.gen(function* () {
+      yield* verifySignature({ request, rawBody });
+      yield* to(Posts, payload);
+      return HttpServerResponse.jsonUnsafe({ ok: true });
     }),
-  ),
-);
+});
+```
+
+Route behavior:
+
+- reads the raw body once
+- parses JSON once
+- validates the route payload schema
+- passes `request`, `rawBody`, typed `payload`, and `to(...)` to the handler
+- returns `400` for invalid body reads, invalid JSON, or invalid route payloads
+- returns `500` for unexpected handler/runtime/publisher failures
 
-Effect.runPromise(program);
+Signature verification is connector-owned and should use `rawBody`.
+
+`ackMode: "after-publish"` publishes collected mutations before the response is completed. `ackMode: "after-enqueue"` enqueues collected mutations and lets the background webhook consumer publish them.
+
+## Connector Definition
+
+```ts
+const connector = Connector.define({
+  name: "producer-example",
+  title: "Producer Example",
+  resources: [Posts],
+  webhooks: [route],
+});
 ```
 
----
+## Ingestion
 
-## Development (concepts and architecture)
+`Ingestion.run(...)` contains the runtime engine. `ConnectorApp.start(...)` is the usual entrypoint for runnable producer CLIs.
 
-### Core concepts
+Current runtime behavior:
 
-- `defineConnector` describes your connector and its entities.
-- `defineEntity` wires live and backfill streams for each entity.
-- `Publisher` is the output boundary (where batches go).
-- `StateStore` tracks cursors and backfill state.
-- `WebhookServerLayer` turns webhook routes into an HTTP server.
+- runs resource backfill, changes, and webhooks concurrently
+- initializes the same initial cutoff for backfill and changes
+- publishes through `Publisher.Publisher`
+- checkpoints only after an accepted publish ACK
+- does not checkpoint rejected publishes
+- allows empty accepted batches to advance state
+- persists resource state through `StateStore.StateStore`
 
-### Layers and Effect services
+Use `StateStore.layerMemory` for development and tests, or provide your own durable `StateStore` implementation.
 
-Connector-kit is designed around Effect services and Layers. Your application should provide:
+## Publisher
 
-- a `Publisher` Layer
-- a `StateStore` Layer
-- an HTTP server Layer (if you use webhooks)
-- any custom services your connector needs (API clients, Effect Config)
+`Publisher.Publisher` is the Effect service boundary for publishing resource mutation batches.
 
-### Testing with VCR
+`Publisher.layerConsole` accepts batches and logs them locally.
 
-VCR is provided via `@useairfoil/effect-vcr` as an Effect `HttpClient` layer. This keeps HTTP recording out of connector logic.
+`Publisher.layerWings(...)` publishes mutations to Wings tables:
 
 ```ts
-import { FetchHttpClient } from "@effect/platform";
-import { NodeFileSystem } from "@effect/platform-node";
-import { FileSystemCassetteStore, VcrHttpClient } from "@useairfoil/effect-vcr";
-import { Layer } from "effect";
-
-const cassetteLayer = CassetteStoreLive.pipe(Layer.provide(NodeFileSystem.layer));
-
-const vcrLayer = VcrHttpClientLayer({
-  cassetteDir: "cassettes",
-  cassetteName: "example",
-  mode: "auto",
-}).pipe(Layer.provide(Layer.mergeAll(FetchHttpClient.layer, cassetteLayer)));
+const publisherLayer = Publisher.layerWings({
+  connector,
+  tables: {
+    posts: "namespaces/default/tables/posts",
+  },
+});
+```
+
+The `tables` map is keyed by resource name. Values can be table names or objects with a table name and optional partition value.
+
+```ts
+Publisher.layerWings({
+  connector,
+  tables: {
+    posts: {
+      name: "namespaces/default/tables/posts",
+      partitionValue: "account_123",
+    },
+  },
+});
 ```
+
+The Wings publisher resolves table metadata during layer construction, validates resource key/version/partition compatibility, sends upserts with full rows, and sends deletes with key/version-only rows.
+
+## Minimal Example
+
+```ts
+import { NodeRuntime } from "@effect/platform-node";
+import {
+  Connector,
+  ConnectorApp,
+  Cursor,
+  Fetch,
+  Publisher,
+  Resource,
+  StateStore,
+  Telemetry,
+} from "@useairfoil/connector-kit";
+import { ConfigProvider, Effect, Layer, Schema } from "effect";
+import { FetchHttpClient } from "effect/unstable/http";
+
+const PostSchema = Schema.Struct({
+  id: Schema.Number,
+  title: Schema.String,
+  updatedAt: Schema.String,
+});
+
+type Post = Schema.Schema.Type<typeof PostSchema>;
+
+const Posts = Resource.entity({
+  name: "posts",
+  schema: PostSchema,
+  key: "id",
+  version: "updatedAt",
+  backfill: Fetch.page({
+    pageCursor: Cursor.number(),
+    cutoff: Cursor.isoDateTime(),
+    fetch: () =>
+      Effect.succeed({
+        mutations: [
+          Resource.upsert({ id: 1, title: "Hello", updatedAt: "2026-01-01T00:00:00.000Z" }),
+        ],
+        nextPageCursor: 1,
+        hasMore: false,
+      }),
+  }),
+});
+
+const connector = Connector.define({
+  name: "producer-example",
+  resources: [Posts],
+});
+
+const EnvLayer = Layer.mergeAll(
+  FetchHttpClient.layer,
+  Layer.succeed(ConfigProvider.ConfigProvider, ConfigProvider.fromEnv()),
+);
+
+const TelemetryLayer = Telemetry.layerOtlpTracing().pipe(Layer.provide(EnvLayer));
+const runtimeLayer = Layer.mergeAll(StateStore.layerMemory, Publisher.layerConsole, TelemetryLayer);
+
+Effect.scoped(ConnectorApp.start(connector, { port: 8080 })).pipe(
+  Effect.provide(runtimeLayer),
+  NodeRuntime.runMain,
+);
+```
+
+## Telemetry
+
+`Telemetry` contains connector-kit span names, span attributes, error annotation helpers, and OTLP tracing layers.
+
+Common entry points:
+
+- `Telemetry.layer(config, options?)`
+- `Telemetry.layerConfig(config, options?)`
+- `Telemetry.layerOtlpTracing(options?)`
+
+Default redacted headers:
+
+- `authorization`
+- `cookie`
+- `set-cookie`
+- `x-api-key`
+- `/api[-_]?key/i`
+- `/secret/i`
+- `/signature/i`
+- `/token/i`
+
+Telemetry environment variables:
+
+| Variable                      | Read by       | Description                                                                                                                |
+| ----------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `OTEL_ENABLED`                | Connector Kit | Enables trace export when `true`. Defaults to `false`.                                                                     |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Connector Kit | OTLP base URL, for example `http://localhost:4318`. Connector Kit appends `/v1/traces`. Required when `OTEL_ENABLED=true`. |
+| `OTEL_EXPORTER_OTLP_HEADERS`  | Connector Kit | Optional comma-separated headers, for example `Authorization=Bearer <token>,X-Axiom-Dataset=<dataset>`.                    |
+| `OTEL_SERVICE_NAME`           | Effect        | Service name resource attribute, for example `producer-shopify`.                                                           |
+| `OTEL_SERVICE_VERSION`        | Effect        | Optional service version resource attribute.                                                                               |
+| `OTEL_RESOURCE_ATTRIBUTES`    | Effect        | Optional comma-separated resource attributes, for example `deployment.environment=production,team=data`.                   |
+
+## Testing
+
+For tests, the most common setup is:
+
+- `StateStore.layerMemory` for state
+- a small in-memory `Publisher.Publisher` test layer
+- `Ingestion.run(...)` or `ConnectorApp.start(...)` inside `Effect.scoped`
+
+Keep HTTP recording concerns outside connector logic by providing a VCR-backed `HttpClient` Layer.

package/dist/chunk-Bp6m_JJh.js

@@ -0,0 +1,13 @@
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __export = (all) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	return target;
+};
+
+//#endregion
+export { __export as t };

package/dist/connector-app/index.d.ts

@@ -0,0 +1,9 @@
+import "../index-DyuT2jzP.js";
+import "../types-ZNrA-Dn0.js";
+import { i as start, n as App, r as StartOptions } from "../index-BlhJCpEk.js";
+import "../service-B7g_lHMI.js";
+import "../index-DaNW63Mv.js";
+import "../index-8KnVpoZp.js";
+import "../index-DK9YcR6W.js";
+import "../index-CQJsFJs3.js";
+export { App, StartOptions, start };

package/dist/connector-app/index.js

@@ -0,0 +1,8 @@
+import "../errors-DHWylqRZ.js";
+import "../telemetry-p0dE5Mdu.js";
+import "../state-store-DG_4QpWG.js";
+import "../server-DAeFWT4o.js";
+import "../ingestion-CMCroK7Y.js";
+import { n as start } from "../connector-app-CvqbfN6R.js";
+
+export { start };

package/dist/connector-app-CvqbfN6R.js

@@ -0,0 +1,32 @@
+import { t as __export } from "./chunk-Bp6m_JJh.js";
+import { n as run } from "./ingestion-CMCroK7Y.js";
+import { DateTime, Effect } from "effect";
+import { NodeHttpServer } from "@effect/platform-node";
+import { HttpRouter } from "effect/unstable/http";
+import { createServer } from "node:http";
+
+//#region src/connector-app/start.ts
+const start = (app, options) => Effect.gen(function* () {
+	const initialCutoff = options.initialCutoff ?? (yield* DateTime.now.pipe(Effect.map(DateTime.formatIso)));
+	const routes = app.webhooks?.map((route) => route.path) ?? [];
+	yield* Effect.logInfo("webhook server ready").pipe(Effect.annotateLogs({
+		port: options.port,
+		routes
+	}));
+	return yield* run(app, {
+		initialCutoff,
+		webhook: {
+			routes: app.webhooks ?? [],
+			healthPath: options.healthPath ?? "/health",
+			disableHttpLogger: options.disableHttpLogger ?? true
+		}
+	}).pipe(Effect.provide(NodeHttpServer.layer(createServer, { port: options.port })));
+});
+
+//#endregion
+//#region src/connector-app/index.ts
+var connector_app_exports = /* @__PURE__ */ __export({ start: () => start });
+
+//#endregion
+export { start as n, connector_app_exports as t };
+//# sourceMappingURL=connector-app-CvqbfN6R.js.map

package/dist/connector-app-CvqbfN6R.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-app-CvqbfN6R.js","names":["runIngestion"],"sources":["../src/connector-app/start.ts","../src/connector-app/index.ts"],"sourcesContent":["import { NodeHttpServer } from \"@effect/platform-node\";\nimport { DateTime, Effect } from \"effect\";\nimport { HttpRouter } from \"effect/unstable/http\";\nimport { createServer } from \"node:http\";\n\nimport type { ConnectorDefinition } from \"../core\";\nimport type { Cursor } from \"../core/types\";\n\nimport { run as runIngestion } from \"../ingestion\";\n\nexport type App = ConnectorDefinition;\n\nexport type StartOptions = {\n  readonly port: number;\n  readonly initialCutoff?: Cursor.Value;\n  readonly healthPath?: HttpRouter.PathInput;\n  readonly disableHttpLogger?: boolean;\n};\n\nexport const start = (app: App, options: StartOptions) =>\n  Effect.gen(function* () {\n    const initialCutoff =\n      options.initialCutoff ?? (yield* DateTime.now.pipe(Effect.map(DateTime.formatIso)));\n    const routes = app.webhooks?.map((route) => route.path) ?? [];\n\n    yield* Effect.logInfo(\"webhook server ready\").pipe(\n      Effect.annotateLogs({ port: options.port, routes }),\n    );\n\n    return yield* runIngestion(app, {\n      initialCutoff,\n      webhook: {\n        routes: app.webhooks ?? [],\n        healthPath: options.healthPath ?? \"/health\",\n        disableHttpLogger: options.disableHttpLogger ?? true,\n      },\n    }).pipe(Effect.provide(NodeHttpServer.layer(createServer, { port: options.port })));\n  });\n","export { start, type App, type StartOptions } from \"./start\";\n"],"mappings":";;;;;;;;AAmBA,MAAa,SAAS,KAAU,YAC9B,OAAO,IAAI,aAAa;CACtB,MAAM,gBACJ,QAAQ,kBAAkB,OAAO,SAAS,IAAI,KAAK,OAAO,IAAI,SAAS,UAAU,CAAC;CACpF,MAAM,SAAS,IAAI,UAAU,KAAK,UAAU,MAAM,KAAK,IAAI,EAAE;AAE7D,QAAO,OAAO,QAAQ,uBAAuB,CAAC,KAC5C,OAAO,aAAa;EAAE,MAAM,QAAQ;EAAM;EAAQ,CAAC,CACpD;AAED,QAAO,OAAOA,IAAa,KAAK;EAC9B;EACA,SAAS;GACP,QAAQ,IAAI,YAAY,EAAE;GAC1B,YAAY,QAAQ,cAAc;GAClC,mBAAmB,QAAQ,qBAAqB;GACjD;EACF,CAAC,CAAC,KAAK,OAAO,QAAQ,eAAe,MAAM,cAAc,EAAE,MAAM,QAAQ,MAAM,CAAC,CAAC,CAAC;EACnF"}

package/dist/errors/index.d.ts

@@ -0,0 +1,2 @@
+import { t as ConnectorError } from "../index-DyuT2jzP.js";
+export { ConnectorError };

package/dist/errors/index.js

@@ -0,0 +1,3 @@
+import { t as ConnectorError } from "../errors-DHWylqRZ.js";
+
+export { ConnectorError };

package/dist/errors-DHWylqRZ.js

@@ -0,0 +1,8 @@
+import { Data } from "effect";
+
+//#region src/errors/connector-error.ts
+var ConnectorError = class extends Data.TaggedError("ConnectorError") {};
+
+//#endregion
+export { ConnectorError as t };
+//# sourceMappingURL=errors-DHWylqRZ.js.map

package/dist/errors-DHWylqRZ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-DHWylqRZ.js","names":[],"sources":["../src/errors/connector-error.ts"],"sourcesContent":["import { Data } from \"effect\";\n\nexport class ConnectorError extends Data.TaggedError(\"ConnectorError\")<{\n  readonly message: string;\n  readonly cause?: unknown;\n}> {}\n"],"mappings":";;;AAEA,IAAa,iBAAb,cAAoC,KAAK,YAAY,iBAAiB,CAGnE"}

package/dist/index-8KnVpoZp.d.ts

@@ -0,0 +1,32 @@
+import { t as ConnectorError } from "./index-DyuT2jzP.js";
+import { l as ResourceDefinition, n as ConnectorDefinition, r as Cursor, y as WebhookRoute } from "./types-ZNrA-Dn0.js";
+import { i as Publisher } from "./service-B7g_lHMI.js";
+import { r as StateStore } from "./index-DaNW63Mv.js";
+import { Effect } from "effect";
+import { HttpRouter, HttpServer } from "effect/unstable/http";
+
+//#region src/ingestion/engine.d.ts
+type RunBaseOptions = {
+  readonly initialCutoff?: Cursor.Value;
+};
+type RunOptions = RunBaseOptions & {
+  readonly webhook?: {
+    readonly routes: ReadonlyArray<WebhookRoute>;
+    readonly healthPath?: HttpRouter.PathInput;
+    readonly disableHttpLogger?: boolean;
+  };
+};
+type RunNoWebhookOptions = RunBaseOptions & {
+  readonly webhook?: undefined;
+};
+type RunWebhookOptions = RunOptions & {
+  readonly webhook: NonNullable<RunOptions["webhook"]>;
+};
+declare function run<const Resources extends ReadonlyArray<ResourceDefinition>>(connector: ConnectorDefinition<Resources>, options?: RunNoWebhookOptions): Effect.Effect<void, ConnectorError, StateStore | Publisher>;
+declare function run<const Resources extends ReadonlyArray<ResourceDefinition>>(connector: ConnectorDefinition<Resources>, options: RunWebhookOptions): Effect.Effect<void, ConnectorError, StateStore | Publisher | HttpServer.HttpServer>;
+declare namespace index_d_exports {
+  export { RunOptions, run };
+}
+//#endregion
+export { RunOptions as n, run as r, index_d_exports as t };
+//# sourceMappingURL=index-8KnVpoZp.d.ts.map

package/dist/index-BlhJCpEk.d.ts

@@ -0,0 +1,124 @@
+import { t as ConnectorError } from "./index-DyuT2jzP.js";
+import { d as ResourceMutation, h as ResourceSchema, i as DeleteValue, l as ResourceDefinition, n as ConnectorDefinition, r as Cursor, s as PageFetch, t as ChangesFetch, v as WebhookHandler } from "./types-ZNrA-Dn0.js";
+import { i as Publisher } from "./service-B7g_lHMI.js";
+import { r as StateStore } from "./index-DaNW63Mv.js";
+import { Config, Effect, Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import * as effect_unstable_http_HttpClient0 from "effect/unstable/http/HttpClient";
+import * as effect_unstable_http_HttpServerError0 from "effect/unstable/http/HttpServerError";
+
+//#region src/core/builder.d.ts
+declare const Connector: {
+  define: <const Resources extends ReadonlyArray<ResourceDefinition>>(definition: ConnectorDefinition<Resources>) => ConnectorDefinition<Resources>;
+};
+declare const Resource: {
+  entity: <S extends ResourceSchema, Payload = never, R = never>(definition: ResourceDefinition<S, Payload, R>) => ResourceDefinition<S, Payload, R>;
+  webhook: <Payload, Row extends object = never>(definition: WebhookHandler<Row, Payload>) => WebhookHandler<Row, Payload>;
+  upsert: <Row extends object>(row: Row) => ResourceMutation<Row>;
+  delete: (options: {
+    readonly key: DeleteValue;
+    readonly version: DeleteValue;
+  }) => ResourceMutation<never>;
+};
+declare const Fetch: {
+  page: <Row extends object = never, R = never>(definition: PageFetch<Row, R>) => PageFetch<Row, R>;
+  changes: <Row extends object = never, R = never>(definition: ChangesFetch<Row, R>) => ChangesFetch<Row, R>;
+};
+declare const Cursor$1: {
+  string: () => Cursor.Definition<string>;
+  number: () => Cursor.Definition<number>;
+  isoDateTime: () => Cursor.Definition<string>;
+  nowIsoDateTime: Effect.Effect<string, never, never>;
+};
+declare namespace telemetry_d_exports {
+  export { Attr, EventAttr, EventName, OtlpTracingConfig, OtlpTracingOptions, SpanName, addCurrentSpanEvent, annotateError, layer, layerConfig, layerOtlpTracing };
+}
+/** Canonical span names emitted by connector-kit runtime instrumentation. */
+declare const SpanName: {
+  readonly batchProcess: "connector.batch.process";
+  readonly webhookDecode: "connector.webhook.decode";
+  readonly webhookHandle: "connector.webhook.handle";
+  readonly publish: "connector.publish";
+  readonly stateSet: "connector.state.set";
+  readonly apiFetch: "connector.api.fetch";
+};
+/** Canonical span attribute names. Keep these stable for collector queries. */
+declare const Attr: {
+  readonly connectorName: "airfoil.connector.name";
+  readonly connectorResourcesCount: "airfoil.connector.resources.count";
+  readonly resourceName: "airfoil.resource.name";
+  readonly resourceSource: "airfoil.resource.source";
+  readonly batchMutations: "airfoil.batch.mutations";
+  readonly webhookPath: "airfoil.webhook.path";
+  readonly publisherSuccess: "airfoil.publisher.success";
+  readonly stateKey: "airfoil.state.key";
+  readonly apiPath: "airfoil.api.path";
+  readonly errorPhase: "airfoil.error.phase";
+  readonly errorType: "airfoil.error.type";
+  readonly errorMessage: "airfoil.error.message";
+  readonly errorDetails: "airfoil.error.details";
+};
+/** Span event names for high-cardinality reproduction details. */
+declare const EventName: {
+  readonly batchCheckpoint: "airfoil.batch.checkpoint";
+};
+/** Event-only attributes. These are intentionally not span attributes. */
+declare const EventAttr: {
+  readonly batchCursor: "airfoil.batch.cursor";
+};
+/** Annotates the active span with phase-aware error metadata before re-failing. */
+declare const annotateError: (phase: string, error: unknown) => Effect.Effect<void, never, never>;
+/** Adds an event to the active span, or no-ops when no span is active. */
+declare const addCurrentSpanEvent: (name: string, attributes?: Record<string, unknown>) => Effect.Effect<void, never, never>;
+/** Transport configuration for OTLP trace export. All fields are direct values. */
+type OtlpTracingConfig = {
+  readonly enabled?: boolean;
+  readonly endpoint?: string;
+  readonly headers?: Record<string, string>;
+};
+/** Runtime options — not config-wrappable since RegExp cannot live in Config. */
+type OtlpTracingOptions = {
+  /** Additional connector-specific header names or regexes to redact from HTTP logs/traces. */
+  readonly redactedHeaders?: ReadonlyArray<string | RegExp>;
+};
+/**
+ * Trace-only OTLP export with sensitive HTTP header redaction.
+ * Takes direct config values — no `ConfigProvider` required.
+ */
+declare const layer: (config?: OtlpTracingConfig, options?: OtlpTracingOptions) => Layer.Layer<never, Error, effect_unstable_http_HttpClient0.HttpClient>;
+/**
+ * Trace-only OTLP export with sensitive HTTP header redaction.
+ * Takes Effect Config-wrapped values — reads from `ConfigProvider`.
+ *
+ * @example
+ * Telemetry.layerConfig({
+ *   enabled: Config.boolean("MY_OTEL_ENABLED"),
+ *   endpoint: Config.string("MY_COLLECTOR_URL"),
+ * })
+ */
+declare const layerConfig: (config: Config.Wrap<OtlpTracingConfig>, options?: OtlpTracingOptions) => Layer.Layer<never, Error | Config.ConfigError, effect_unstable_http_HttpClient0.HttpClient>;
+/**
+ * Trace-only OTLP export with sensitive HTTP header redaction.
+ * Zero-config shortcut that reads the standard `OTEL_*` env var names.
+ *
+ * Reads `OTEL_ENABLED`, `OTEL_EXPORTER_OTLP_ENDPOINT`, and
+ * `OTEL_EXPORTER_OTLP_HEADERS`. Effect's OTLP resource handling reads
+ * `OTEL_SERVICE_NAME`, `OTEL_SERVICE_VERSION`, and `OTEL_RESOURCE_ATTRIBUTES`.
+ */
+declare const layerOtlpTracing: (options?: OtlpTracingOptions) => Layer.Layer<never, Error | Config.ConfigError, effect_unstable_http_HttpClient0.HttpClient>;
+//#endregion
+//#region src/connector-app/start.d.ts
+type App = ConnectorDefinition;
+type StartOptions = {
+  readonly port: number;
+  readonly initialCutoff?: Cursor.Value;
+  readonly healthPath?: HttpRouter.PathInput;
+  readonly disableHttpLogger?: boolean;
+};
+declare const start: (app: App, options: StartOptions) => Effect.Effect<void, ConnectorError | effect_unstable_http_HttpServerError0.ServeError, StateStore | Publisher>;
+declare namespace index_d_exports {
+  export { App, StartOptions, start };
+}
+//#endregion
+export { telemetry_d_exports as a, Fetch as c, start as i, Resource as l, App as n, Connector as o, StartOptions as r, Cursor$1 as s, index_d_exports as t };
+//# sourceMappingURL=index-BlhJCpEk.d.ts.map