@useairfoil/connector-kit 0.4.0 → 0.5.0

package/dist/telemetry-p0dE5Mdu.js

@@ -0,0 +1,171 @@
+import { t as __export } from "./chunk-Bp6m_JJh.js";
+import { Cause, Config, Context, Effect, Layer, Option } from "effect";
+import { Headers } from "effect/unstable/http";
+import * as Observability from "effect/unstable/observability";
+
+//#region src/publisher/service.ts
+var Publisher = class extends Context.Service()("@useairfoil/connector-kit/Publisher") {};
+
+//#endregion
+//#region src/telemetry.ts
+var telemetry_exports = /* @__PURE__ */ __export({
+	Attr: () => Attr,
+	EventAttr: () => EventAttr,
+	EventName: () => EventName,
+	SpanName: () => SpanName,
+	addCurrentSpanEvent: () => addCurrentSpanEvent,
+	annotateError: () => annotateError,
+	layer: () => layer,
+	layerConfig: () => layerConfig,
+	layerOtlpTracing: () => layerOtlpTracing
+});
+/** Canonical span names emitted by connector-kit runtime instrumentation. */
+const SpanName = {
+	batchProcess: "connector.batch.process",
+	webhookDecode: "connector.webhook.decode",
+	webhookHandle: "connector.webhook.handle",
+	publish: "connector.publish",
+	stateSet: "connector.state.set",
+	apiFetch: "connector.api.fetch"
+};
+/** Canonical span attribute names. Keep these stable for collector queries. */
+const Attr = {
+	connectorName: "airfoil.connector.name",
+	connectorResourcesCount: "airfoil.connector.resources.count",
+	resourceName: "airfoil.resource.name",
+	resourceSource: "airfoil.resource.source",
+	batchMutations: "airfoil.batch.mutations",
+	webhookPath: "airfoil.webhook.path",
+	publisherSuccess: "airfoil.publisher.success",
+	stateKey: "airfoil.state.key",
+	apiPath: "airfoil.api.path",
+	errorPhase: "airfoil.error.phase",
+	errorType: "airfoil.error.type",
+	errorMessage: "airfoil.error.message",
+	errorDetails: "airfoil.error.details"
+};
+/** Span event names for high-cardinality reproduction details. */
+const EventName = { batchCheckpoint: "airfoil.batch.checkpoint" };
+/** Event-only attributes. These are intentionally not span attributes. */
+const EventAttr = { batchCursor: "airfoil.batch.cursor" };
+const isRecord = (value) => typeof value === "object" && value !== null;
+const maxErrorMessageLength = 500;
+const OtlpEnvConfig = Config.all({
+	enabled: Config.boolean("OTEL_ENABLED").pipe(Config.withDefault(false)),
+	baseUrl: Config.option(Config.string("OTEL_EXPORTER_OTLP_ENDPOINT")),
+	rawHeaders: Config.option(Config.string("OTEL_EXPORTER_OTLP_HEADERS"))
+});
+const defaultRedactedHeaders = [
+	"authorization",
+	"cookie",
+	"set-cookie",
+	"x-api-key",
+	/api[-_]?key/i,
+	/secret/i,
+	/signature/i,
+	/token/i
+];
+const parseOtelHeaders = (value) => Object.fromEntries(value.split(",").map((entry) => entry.trim()).filter(Boolean).flatMap((entry) => {
+	const separator = entry.indexOf("=");
+	if (separator < 1) return [];
+	return [[entry.slice(0, separator).trim(), entry.slice(separator + 1).trim()]];
+}));
+const appendPath = (baseUrl, path) => `${baseUrl.replace(/\/$/, "")}/${path.replace(/^\//, "")}`;
+/**
+* Best-effort stable error classifier for span metadata.
+*
+* Effect/Data tagged errors expose `_tag`; that is the most useful value for
+* connector bugs (`ConnectorError`, `InvalidWebhookPayloadError`, etc.). For
+* non-tagged errors we fall back to the JS `Error.name`, then constructor name,
+* then the primitive type.
+*/
+const errorType = (error) => {
+	if (isRecord(error) && typeof error._tag === "string") return String(error._tag);
+	if (error instanceof Error) return error.name;
+	if (isRecord(error) && typeof error.constructor?.name === "string") return error.constructor.name;
+	return typeof error;
+};
+/**
+* Human-readable error summary for span metadata.
+*
+* Tagged errors in this package carry a `message` field, so this preserves the
+* important diagnostic text. Unknown object failures are intentionally reduced
+* to their type; full structured error payloads belong in logs, not span attrs.
+*/
+const errorMessage = (error) => {
+	const message = (() => {
+		if (isRecord(error) && typeof error.message === "string") return error.message;
+		if (typeof error === "string") return error;
+		return errorType(error);
+	})();
+	if (message.length > maxErrorMessageLength) return `${message.slice(0, maxErrorMessageLength)}...`;
+	return message;
+};
+const errorDetails = (error) => {
+	if (!isRecord(error) || error.cause === void 0) return void 0;
+	return Cause.pretty(Cause.die(error.cause));
+};
+/** Annotates the active span with phase-aware error metadata before re-failing. */
+const annotateError = (phase, error) => {
+	const details = errorDetails(error);
+	return Effect.annotateCurrentSpan({
+		[Attr.errorPhase]: phase,
+		[Attr.errorType]: errorType(error),
+		[Attr.errorMessage]: errorMessage(error),
+		...details !== void 0 ? { [Attr.errorDetails]: details } : {}
+	});
+};
+/** Adds an event to the active span, or no-ops when no span is active. */
+const addCurrentSpanEvent = (name, attributes) => Effect.currentSpan.pipe(Effect.flatMap((span) => Effect.clockWith((clock) => Effect.sync(() => span.event(name, clock.currentTimeNanosUnsafe(), attributes)))), Effect.ignore);
+const buildOtlpTracingLayer = (config, options) => Effect.gen(function* () {
+	const allRedacted = [...defaultRedactedHeaders, ...options.redactedHeaders ?? []];
+	const RedactionLayer = Layer.succeed(Headers.CurrentRedactedNames)(allRedacted);
+	if (!config.enabled) return RedactionLayer;
+	if (!config.endpoint) return yield* Effect.fail(/* @__PURE__ */ new Error("enabled=true requires endpoint"));
+	yield* Effect.logInfo("telemetry enabled").pipe(Effect.annotateLogs({
+		endpoint: config.endpoint,
+		headers: config.headers ? Object.keys(config.headers) : []
+	}));
+	return Layer.mergeAll(RedactionLayer, Observability.OtlpTracer.layer({
+		url: appendPath(config.endpoint, "/v1/traces"),
+		headers: config.headers
+	}).pipe(Layer.provide(Observability.OtlpSerialization.layerJson)));
+});
+/**
+* Trace-only OTLP export with sensitive HTTP header redaction.
+* Takes direct config values — no `ConfigProvider` required.
+*/
+const layer = (config = {}, options = {}) => Layer.unwrap(buildOtlpTracingLayer(config, options));
+/**
+* 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"),
+* })
+*/
+const layerConfig = (config, options = {}) => Layer.unwrap(Effect.gen(function* () {
+	return yield* buildOtlpTracingLayer(yield* Config.unwrap(config), options);
+}));
+/**
+* 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`.
+*/
+const layerOtlpTracing = (options = {}) => Layer.unwrap(Effect.gen(function* () {
+	const raw = yield* OtlpEnvConfig;
+	return yield* buildOtlpTracingLayer({
+		enabled: raw.enabled,
+		endpoint: Option.getOrUndefined(raw.baseUrl),
+		headers: Option.isSome(raw.rawHeaders) ? parseOtelHeaders(raw.rawHeaders.value) : void 0
+	}, options);
+}));
+
+//#endregion
+export { addCurrentSpanEvent as a, Publisher as c, SpanName as i, EventAttr as n, annotateError as o, EventName as r, telemetry_exports as s, Attr as t };
+//# sourceMappingURL=telemetry-p0dE5Mdu.js.map

package/dist/telemetry-p0dE5Mdu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-p0dE5Mdu.js","names":["defaultRedactedHeaders: ReadonlyArray<string | RegExp>"],"sources":["../src/publisher/service.ts","../src/telemetry.ts"],"sourcesContent":["import type * as Wings from \"@useairfoil/wings\";\nimport type * as Effect from \"effect/Effect\";\n\nimport { Context } from \"effect\";\n\nimport type { ResourceBatch } from \"../core/types\";\nimport type { ConnectorError } from \"../errors\";\n\nexport type PublishSource = \"backfill\" | \"changes\" | \"webhook\";\n\nexport type PublishAck =\n  | {\n      readonly status: \"accepted\";\n      readonly resource: string;\n      readonly partition?: Wings.PartitionValue.PartitionValue;\n    }\n  | {\n      readonly status: \"rejected\";\n      readonly resource: string;\n      readonly reason: string;\n      readonly rejectedRows?: number;\n      readonly partition?: Wings.PartitionValue.PartitionValue;\n    };\n\nexport type PublishOptions = {\n  readonly resource: string;\n  readonly source: PublishSource;\n  readonly batch: ResourceBatch;\n};\n\nexport interface PublisherService {\n  readonly publish: (options: PublishOptions) => Effect.Effect<PublishAck, ConnectorError>;\n}\n\nexport class Publisher extends Context.Service<Publisher, PublisherService>()(\n  \"@useairfoil/connector-kit/Publisher\",\n) {}\n","import { Cause, Config, Effect, Layer, Option } from \"effect\";\nimport { Headers } from \"effect/unstable/http\";\nimport * as Observability from \"effect/unstable/observability\";\n\n/** Canonical span names emitted by connector-kit runtime instrumentation. */\nexport const SpanName = {\n  batchProcess: \"connector.batch.process\",\n  webhookDecode: \"connector.webhook.decode\",\n  webhookHandle: \"connector.webhook.handle\",\n  publish: \"connector.publish\",\n  stateSet: \"connector.state.set\",\n  apiFetch: \"connector.api.fetch\",\n} as const;\n\n/** Canonical span attribute names. Keep these stable for collector queries. */\nexport const Attr = {\n  connectorName: \"airfoil.connector.name\",\n  connectorResourcesCount: \"airfoil.connector.resources.count\",\n  resourceName: \"airfoil.resource.name\",\n  resourceSource: \"airfoil.resource.source\",\n  batchMutations: \"airfoil.batch.mutations\",\n  webhookPath: \"airfoil.webhook.path\",\n  publisherSuccess: \"airfoil.publisher.success\",\n  stateKey: \"airfoil.state.key\",\n  apiPath: \"airfoil.api.path\",\n  errorPhase: \"airfoil.error.phase\",\n  errorType: \"airfoil.error.type\",\n  errorMessage: \"airfoil.error.message\",\n  errorDetails: \"airfoil.error.details\",\n} as const;\n\n/** Span event names for high-cardinality reproduction details. */\nexport const EventName = {\n  batchCheckpoint: \"airfoil.batch.checkpoint\",\n} as const;\n\n/** Event-only attributes. These are intentionally not span attributes. */\nexport const EventAttr = {\n  batchCursor: \"airfoil.batch.cursor\",\n} as const;\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null;\n\nconst maxErrorMessageLength = 500;\n\nconst OtlpEnvConfig = Config.all({\n  enabled: Config.boolean(\"OTEL_ENABLED\").pipe(Config.withDefault(false)),\n  baseUrl: Config.option(Config.string(\"OTEL_EXPORTER_OTLP_ENDPOINT\")),\n  rawHeaders: Config.option(Config.string(\"OTEL_EXPORTER_OTLP_HEADERS\")),\n});\n\nconst defaultRedactedHeaders: ReadonlyArray<string | RegExp> = [\n  \"authorization\",\n  \"cookie\",\n  \"set-cookie\",\n  \"x-api-key\",\n  /api[-_]?key/i,\n  /secret/i,\n  /signature/i,\n  /token/i,\n];\n\nconst parseOtelHeaders = (value: string): Record<string, string> =>\n  Object.fromEntries(\n    value\n      .split(\",\")\n      .map((entry) => entry.trim())\n      .filter(Boolean)\n      .flatMap((entry) => {\n        const separator = entry.indexOf(\"=\");\n        if (separator < 1) return [];\n        return [[entry.slice(0, separator).trim(), entry.slice(separator + 1).trim()]];\n      }),\n  );\n\nconst appendPath = (baseUrl: string, path: string) =>\n  `${baseUrl.replace(/\\/$/, \"\")}/${path.replace(/^\\//, \"\")}`;\n\n/**\n * Best-effort stable error classifier for span metadata.\n *\n * Effect/Data tagged errors expose `_tag`; that is the most useful value for\n * connector bugs (`ConnectorError`, `InvalidWebhookPayloadError`, etc.). For\n * non-tagged errors we fall back to the JS `Error.name`, then constructor name,\n * then the primitive type.\n */\nconst errorType = (error: unknown) => {\n  if (isRecord(error) && typeof error._tag === \"string\") {\n    return String(error._tag);\n  }\n  if (error instanceof Error) {\n    return error.name;\n  }\n  if (isRecord(error) && typeof error.constructor?.name === \"string\") {\n    return error.constructor.name;\n  }\n  return typeof error;\n};\n\n/**\n * Human-readable error summary for span metadata.\n *\n * Tagged errors in this package carry a `message` field, so this preserves the\n * important diagnostic text. Unknown object failures are intentionally reduced\n * to their type; full structured error payloads belong in logs, not span attrs.\n */\nconst errorMessage = (error: unknown) => {\n  const message = (() => {\n    if (isRecord(error) && typeof error.message === \"string\") {\n      return error.message;\n    }\n    if (typeof error === \"string\") {\n      return error;\n    }\n    return errorType(error);\n  })();\n\n  if (message.length > maxErrorMessageLength) {\n    return `${message.slice(0, maxErrorMessageLength)}...`;\n  }\n\n  return message;\n};\n\nconst errorDetails = (error: unknown): string | undefined => {\n  if (!isRecord(error) || error.cause === undefined) return undefined;\n  return Cause.pretty(Cause.die(error.cause));\n};\n\n/** Annotates the active span with phase-aware error metadata before re-failing. */\nexport const annotateError = (phase: string, error: unknown) => {\n  const details = errorDetails(error);\n  return Effect.annotateCurrentSpan({\n    [Attr.errorPhase]: phase,\n    [Attr.errorType]: errorType(error),\n    [Attr.errorMessage]: errorMessage(error),\n    ...(details !== undefined ? { [Attr.errorDetails]: details } : {}),\n  });\n};\n\n/** Adds an event to the active span, or no-ops when no span is active. */\nexport const addCurrentSpanEvent = (name: string, attributes?: Record<string, unknown>) =>\n  Effect.currentSpan.pipe(\n    Effect.flatMap((span) =>\n      Effect.clockWith((clock) =>\n        Effect.sync(() => span.event(name, clock.currentTimeNanosUnsafe(), attributes)),\n      ),\n    ),\n    Effect.ignore,\n  );\n\n/** Transport configuration for OTLP trace export. All fields are direct values. */\nexport type OtlpTracingConfig = {\n  readonly enabled?: boolean;\n  readonly endpoint?: string;\n  readonly headers?: Record<string, string>;\n};\n\n/** Runtime options — not config-wrappable since RegExp cannot live in Config. */\nexport type OtlpTracingOptions = {\n  /** Additional connector-specific header names or regexes to redact from HTTP logs/traces. */\n  readonly redactedHeaders?: ReadonlyArray<string | RegExp>;\n};\n\nconst buildOtlpTracingLayer = (config: OtlpTracingConfig, options: OtlpTracingOptions) =>\n  Effect.gen(function* () {\n    const allRedacted = [...defaultRedactedHeaders, ...(options.redactedHeaders ?? [])];\n    const RedactionLayer = Layer.succeed(Headers.CurrentRedactedNames)(allRedacted);\n\n    if (!config.enabled) {\n      return RedactionLayer;\n    }\n\n    if (!config.endpoint) {\n      return yield* Effect.fail(new Error(\"enabled=true requires endpoint\"));\n    }\n\n    yield* Effect.logInfo(\"telemetry enabled\").pipe(\n      Effect.annotateLogs({\n        endpoint: config.endpoint,\n        headers: config.headers ? Object.keys(config.headers) : [],\n      }),\n    );\n\n    return Layer.mergeAll(\n      RedactionLayer,\n      Observability.OtlpTracer.layer({\n        url: appendPath(config.endpoint, \"/v1/traces\"),\n        headers: config.headers,\n      }).pipe(Layer.provide(Observability.OtlpSerialization.layerJson)),\n    );\n  });\n\n/**\n * Trace-only OTLP export with sensitive HTTP header redaction.\n * Takes direct config values — no `ConfigProvider` required.\n */\nexport const layer = (config: OtlpTracingConfig = {}, options: OtlpTracingOptions = {}) =>\n  Layer.unwrap(buildOtlpTracingLayer(config, options));\n\n/**\n * Trace-only OTLP export with sensitive HTTP header redaction.\n * Takes Effect Config-wrapped values — reads from `ConfigProvider`.\n *\n * @example\n * Telemetry.layerConfig({\n *   enabled: Config.boolean(\"MY_OTEL_ENABLED\"),\n *   endpoint: Config.string(\"MY_COLLECTOR_URL\"),\n * })\n */\nexport const layerConfig = (\n  config: Config.Wrap<OtlpTracingConfig>,\n  options: OtlpTracingOptions = {},\n) =>\n  Layer.unwrap(\n    Effect.gen(function* () {\n      const resolved = yield* Config.unwrap(config);\n      return yield* buildOtlpTracingLayer(resolved, options);\n    }),\n  );\n\n/**\n * Trace-only OTLP export with sensitive HTTP header redaction.\n * Zero-config shortcut that reads the standard `OTEL_*` env var names.\n *\n * Reads `OTEL_ENABLED`, `OTEL_EXPORTER_OTLP_ENDPOINT`, and\n * `OTEL_EXPORTER_OTLP_HEADERS`. Effect's OTLP resource handling reads\n * `OTEL_SERVICE_NAME`, `OTEL_SERVICE_VERSION`, and `OTEL_RESOURCE_ATTRIBUTES`.\n */\nexport const layerOtlpTracing = (options: OtlpTracingOptions = {}) =>\n  Layer.unwrap(\n    Effect.gen(function* () {\n      const raw = yield* OtlpEnvConfig;\n      return yield* buildOtlpTracingLayer(\n        {\n          enabled: raw.enabled,\n          endpoint: Option.getOrUndefined(raw.baseUrl),\n          headers: Option.isSome(raw.rawHeaders)\n            ? parseOtelHeaders(raw.rawHeaders.value)\n            : undefined,\n        },\n        options,\n      );\n    }),\n  );\n"],"mappings":"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"}

package/dist/types-ZNrA-Dn0.d.ts

@@ -0,0 +1,160 @@
+import { t as ConnectorError } from "./index-DyuT2jzP.js";
+import { Duration, Effect, Schema } from "effect";
+import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+
+//#region src/core/types.d.ts
+declare namespace Cursor {
+  type Value = string | number | Date;
+  type Kind = "string" | "number" | "isoDateTime";
+  type Definition<T extends Value = Value> = {
+    readonly kind: Kind;
+    readonly decode: (value: unknown) => Effect.Effect<T, ConnectorError>;
+  };
+}
+type DeleteValue = string | number | boolean | Date;
+type ResourceMutation<Row extends object = object> = {
+  readonly op: "upsert";
+  readonly row: Row;
+} | {
+  readonly op: "delete";
+  readonly key: DeleteValue;
+  readonly version: DeleteValue;
+};
+type ResourceBatch<Row extends object = object> = {
+  readonly cursor?: Cursor.Value;
+  readonly mutations: ReadonlyArray<ResourceMutation<Row>>;
+};
+type ResourceState = {
+  readonly backfill?: {
+    readonly cutoff: Cursor.Value;
+    readonly pageCursor?: Cursor.Value;
+    readonly completed: boolean;
+  };
+  readonly changes?: {
+    readonly cursor: Cursor.Value;
+  };
+};
+type ResourceSchema = Schema.Decoder<object>;
+/**
+ * Takes a resource schema and returns its decoded row object type.
+ *
+ * @example
+ * ```ts
+ * const ProductSchema = Schema.Struct({ id: Schema.String, updatedAt: Schema.String });
+ * type Product = ResourceRow<typeof ProductSchema>;
+ * // Result:
+ * // type Product = { readonly id: string; readonly updatedAt: string }
+ * ```
+ */
+type ResourceRow<S$1 extends ResourceSchema> = Schema.Schema.Type<S$1>;
+/**
+ * Takes a resource schema and returns the string keys available on its row type.
+ *
+ * @example
+ * ```ts
+ * const ProductSchema = Schema.Struct({ id: Schema.String, updatedAt: Schema.String });
+ * type ProductField = ResourceField<typeof ProductSchema>;
+ * // Result:
+ * // type ProductField = "id" | "updatedAt"
+ *
+ * const key: ResourceField<typeof ProductSchema> = "id";
+ * ```
+ */
+type ResourceField<S$1 extends ResourceSchema> = keyof ResourceRow<S$1> & string;
+type FetchPageResult<Row extends object> = {
+  readonly mutations: ReadonlyArray<ResourceMutation<Row>>;
+  readonly nextPageCursor?: Cursor.Value;
+  readonly hasMore: boolean;
+};
+type PageFetch<Row extends object, R = never> = {
+  readonly pageCursor: Cursor.Definition;
+  readonly cutoff: Cursor.Definition;
+  readonly fetch: (input: {
+    readonly pageCursor?: Cursor.Value;
+    readonly cutoff: Cursor.Value;
+  }) => Effect.Effect<FetchPageResult<Row>, ConnectorError, R>;
+};
+type FetchChangesResult<Row extends object> = {
+  readonly mutations: ReadonlyArray<ResourceMutation<Row>>;
+  readonly cursor: Cursor.Value;
+};
+type ChangesFetch<Row extends object, R = never> = {
+  readonly cursor: Cursor.Definition;
+  readonly interval?: Duration.Input;
+  readonly fetch: (input: {
+    readonly cursor: Cursor.Value;
+  }) => Effect.Effect<FetchChangesResult<Row>, ConnectorError, R>;
+};
+type WebhookHandler<Row extends object, Payload$1> = {
+  readonly schema: Schema.Decoder<Payload$1>;
+  handler(input: {
+    readonly payload: Payload$1;
+  }): Effect.Effect<ReadonlyArray<ResourceMutation<Row>>, ConnectorError>;
+};
+type ResourceDefinition<S$1 extends ResourceSchema = ResourceSchema, Payload$1 = unknown, R = never> = {
+  readonly name: string;
+  readonly schema: S$1;
+  readonly key: ResourceField<NoInfer<S$1>>;
+  readonly version: ResourceField<NoInfer<S$1>>;
+  readonly partition?: {
+    readonly required: boolean;
+  };
+  readonly backfill?: PageFetch<ResourceRow<NoInfer<S$1>>, R>;
+  readonly changes?: ChangesFetch<ResourceRow<NoInfer<S$1>>, R>;
+  readonly webhook?: WebhookHandler<ResourceRow<NoInfer<S$1>>, Payload$1>;
+};
+/**
+ * Takes a connector resource tuple and returns a `{ [resourceName]: rowType }`
+ * map.
+ *
+ * @example
+ * ```ts
+ * type Rows = ResourceRows<[typeof Products, typeof Orders]>;
+ * // Result:
+ * // type Rows = {
+ * //   readonly products: Product;
+ * //   readonly orders: Order;
+ * // }
+ *
+ * type ProductRow = Rows["products"];
+ * // Result:
+ * // type ProductRow = Product
+ * ```
+ */
+type ResourceRows<Resources extends ReadonlyArray<ResourceDefinition>> = { readonly [Resource in Resources[number] as Resource["name"]]: Resource extends ResourceDefinition<infer S, unknown, unknown> ? ResourceRow<S> : never };
+/**
+ * Takes a resource definition and returns the payload type accepted by
+ * `to(resource, payload)`.
+ *
+ * @example
+ * ```ts
+ * type ProductPayload = ResourcePayload<typeof Products>;
+ * // Result, if Products was defined with a ProductEvent webhook schema:
+ * // type ProductPayload = ProductEvent
+ * ```
+ */
+type ResourcePayload<R> = R extends ResourceDefinition<ResourceSchema, infer Payload, unknown> ? Payload : never;
+type WebhookAckMode = "after-enqueue" | "after-publish";
+type WebhookRouteContext<Resources extends ReadonlyArray<ResourceDefinition> = ReadonlyArray<ResourceDefinition>, Payload$1 = unknown> = {
+  readonly request: HttpServerRequest.HttpServerRequest;
+  readonly rawBody: Uint8Array;
+  readonly payload: Payload$1;
+  /** Decodes and collects mutations for a resource-owned webhook handler. */
+  readonly to: <Resource$1 extends Resources[number]>(resource: Resource$1, payload: ResourcePayload<Resource$1>) => Effect.Effect<void, ConnectorError>;
+};
+type WebhookRoute<Resources extends ReadonlyArray<ResourceDefinition> = ReadonlyArray<ResourceDefinition>, Payload$1 = unknown> = {
+  readonly path: HttpRouter.PathInput;
+  readonly ackMode: WebhookAckMode;
+  readonly schema: Schema.Decoder<Payload$1>;
+  handler(context: WebhookRouteContext<Resources, Payload$1>): Effect.Effect<HttpServerResponse.HttpServerResponse, unknown>;
+};
+type WebhookRouteInput<Resources extends ReadonlyArray<ResourceDefinition>, Payload$1> = WebhookRoute<Resources, Payload$1>;
+type ConnectorDefinition<Resources extends ReadonlyArray<ResourceDefinition> = ReadonlyArray<ResourceDefinition>> = {
+  readonly name: string;
+  readonly title?: string;
+  readonly resources: Resources;
+  readonly webhooks?: ReadonlyArray<WebhookRoute>;
+};
+//#endregion
+export { WebhookAckMode as _, FetchChangesResult as a, WebhookRouteContext as b, ResourceBatch as c, ResourceMutation as d, ResourcePayload as f, ResourceState as g, ResourceSchema as h, DeleteValue as i, ResourceDefinition as l, ResourceRows as m, ConnectorDefinition as n, FetchPageResult as o, ResourceRow as p, Cursor as r, PageFetch as s, ChangesFetch as t, ResourceField as u, WebhookHandler as v, WebhookRouteInput as x, WebhookRoute as y };
+//# sourceMappingURL=types-ZNrA-Dn0.d.ts.map

package/dist/webhook/index.d.ts

@@ -0,0 +1,5 @@
+import "../index-DyuT2jzP.js";
+import { _ as WebhookAckMode, b as WebhookRouteContext, x as WebhookRouteInput, y as WebhookRoute } from "../types-ZNrA-Dn0.js";
+import "../service-B7g_lHMI.js";
+import { n as route, r as router } from "../index-CQJsFJs3.js";
+export { WebhookAckMode, WebhookRoute, WebhookRouteContext, WebhookRouteInput, route, router };

package/dist/webhook/index.js

@@ -0,0 +1,6 @@
+import "../errors-DHWylqRZ.js";
+import "../telemetry-p0dE5Mdu.js";
+import { n as router } from "../server-DAeFWT4o.js";
+import { t as route } from "../webhook-BSA-tXtU.js";
+
+export { route, router };

package/dist/webhook-BSA-tXtU.js

@@ -0,0 +1,13 @@
+import { t as __export } from "./chunk-Bp6m_JJh.js";
+import { n as router } from "./server-DAeFWT4o.js";
+
+//#region src/webhook/index.ts
+var webhook_exports = /* @__PURE__ */ __export({
+	route: () => route,
+	router: () => router
+});
+const route = (definition) => definition;
+
+//#endregion
+export { webhook_exports as n, route as t };
+//# sourceMappingURL=webhook-BSA-tXtU.js.map

package/dist/webhook-BSA-tXtU.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-BSA-tXtU.js","names":[],"sources":["../src/webhook/index.ts"],"sourcesContent":["import type { ResourceDefinition, WebhookRoute, WebhookRouteInput } from \"../core/types\";\n\nexport { router } from \"./server\";\nexport type { WebhookAckMode, WebhookRoute, WebhookRouteContext, WebhookRouteInput } from \"./types\";\n\nexport const route = <const Resources extends ReadonlyArray<ResourceDefinition>, Payload>(\n  definition: WebhookRouteInput<Resources, Payload>,\n): WebhookRoute<Resources, Payload> => definition;\n"],"mappings":";;;;;;;;AAKA,MAAa,SACX,eACqC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useairfoil/connector-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "repository": "useairfoil/typescript-sdk",
   "files": [
     "dist",
@@ -15,6 +15,36 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./connector-app": {
+      "types": "./dist/connector-app/index.d.ts",
+      "import": "./dist/connector-app/index.js",
+      "default": "./dist/connector-app/index.js"
+    },
+    "./ingestion": {
+      "types": "./dist/ingestion/index.d.ts",
+      "import": "./dist/ingestion/index.js",
+      "default": "./dist/ingestion/index.js"
+    },
+    "./publisher": {
+      "types": "./dist/publisher/index.d.ts",
+      "import": "./dist/publisher/index.js",
+      "default": "./dist/publisher/index.js"
+    },
+    "./state-store": {
+      "types": "./dist/state-store/index.d.ts",
+      "import": "./dist/state-store/index.js",
+      "default": "./dist/state-store/index.js"
+    },
+    "./webhook": {
+      "types": "./dist/webhook/index.d.ts",
+      "import": "./dist/webhook/index.js",
+      "default": "./dist/webhook/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.ts",
+      "import": "./dist/errors/index.js",
+      "default": "./dist/errors/index.js"
     }
   },
   "scripts": {
@@ -24,19 +54,18 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@useairfoil/flight": "0.4.0",
-    "@useairfoil/wings": "0.4.0",
-    "consola": "^3.4.2",
-    "json-stable-stringify": "^1.3.0"
+    "@effect/platform-node": "4.0.0-beta.83",
+    "@useairfoil/flight": "0.4.3",
+    "@useairfoil/wings": "0.4.1"
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.0-beta.54",
+    "@effect/vitest": "4.0.0-beta.83",
     "@types/node": "^24.2.0",
     "tsdown": "^0.15.6",
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
-    "effect": "4.0.0-beta.54"
+    "effect": "4.0.0-beta.83"
   },
   "peerDependenciesMeta": {
     "effect": {

package/src/connector-app/index.ts

@@ -0,0 +1 @@
+export { start, type App, type StartOptions } from "./start";

package/src/connector-app/start.ts

@@ -0,0 +1,38 @@
+import { NodeHttpServer } from "@effect/platform-node";
+import { DateTime, Effect } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { createServer } from "node:http";
+
+import type { ConnectorDefinition } from "../core";
+import type { Cursor } from "../core/types";
+
+import { run as runIngestion } from "../ingestion";
+
+export type App = ConnectorDefinition;
+
+export type StartOptions = {
+  readonly port: number;
+  readonly initialCutoff?: Cursor.Value;
+  readonly healthPath?: HttpRouter.PathInput;
+  readonly disableHttpLogger?: boolean;
+};
+
+export const start = (app: App, options: StartOptions) =>
+  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* runIngestion(app, {
+      initialCutoff,
+      webhook: {
+        routes: app.webhooks ?? [],
+        healthPath: options.healthPath ?? "/health",
+        disableHttpLogger: options.disableHttpLogger ?? true,
+      },
+    }).pipe(Effect.provide(NodeHttpServer.layer(createServer, { port: options.port })));
+  });

package/src/core/builder.ts

@@ -1,12 +1,79 @@
-import type { ConnectorDefinition, EntityDefinition, EntitySchema, EventDefinition } from "./types";
+import { DateTime, Effect } from "effect";
 
-export const defineConnector = <
-  const Entities extends ReadonlyArray<EntityDefinition<EntitySchema>>,
-  const Events extends ReadonlyArray<EventDefinition<EntitySchema>>,
->(
-  definition: ConnectorDefinition<Entities, Events>,
-) => definition;
+import type {
+  ChangesFetch,
+  ConnectorDefinition,
+  Cursor as CursorType,
+  DeleteValue,
+  PageFetch,
+  ResourceDefinition,
+  ResourceMutation,
+  ResourceSchema,
+  WebhookHandler,
+} from "./types";
 
-export const defineEntity = <S extends EntitySchema>(definition: EntityDefinition<S>) => definition;
+import { ConnectorError } from "../errors";
 
-export const defineEvent = <S extends EntitySchema>(definition: EventDefinition<S>) => definition;
+export const Connector = {
+  define: <const Resources extends ReadonlyArray<ResourceDefinition>>(
+    definition: ConnectorDefinition<Resources>,
+  ) => definition,
+};
+
+export const Resource = {
+  entity: <S extends ResourceSchema, Payload = never, R = never>(
+    definition: ResourceDefinition<S, Payload, R>,
+  ): ResourceDefinition<S, Payload, R> => definition,
+
+  webhook: <Payload, Row extends object = never>(definition: WebhookHandler<Row, Payload>) =>
+    definition,
+
+  upsert: <Row extends object>(row: Row): ResourceMutation<Row> => ({ op: "upsert", row }),
+
+  delete: (options: {
+    readonly key: DeleteValue;
+    readonly version: DeleteValue;
+  }): ResourceMutation<never> => ({
+    op: "delete",
+    key: options.key,
+    version: options.version,
+  }),
+};
+
+export const Fetch = {
+  page: <Row extends object = never, R = never>(definition: PageFetch<Row, R>) => definition,
+  changes: <Row extends object = never, R = never>(definition: ChangesFetch<Row, R>) => definition,
+};
+
+const decodeFailure = (kind: string, value: unknown) =>
+  new ConnectorError({ message: `Invalid ${kind} cursor value: ${String(value)}` });
+
+export const Cursor = {
+  string: (): CursorType.Definition<string> => ({
+    kind: "string",
+    decode: (value) =>
+      typeof value === "string"
+        ? Effect.succeed(value)
+        : Effect.fail(decodeFailure("string", value)),
+  }),
+
+  number: (): CursorType.Definition<number> => ({
+    kind: "number",
+    decode: (value) =>
+      typeof value === "number" && Number.isFinite(value)
+        ? Effect.succeed(value)
+        : Effect.fail(decodeFailure("number", value)),
+  }),
+
+  isoDateTime: (): CursorType.Definition<string> => ({
+    kind: "isoDateTime",
+    decode: (value) => {
+      if (typeof value !== "string" || Number.isNaN(Date.parse(value))) {
+        return Effect.fail(decodeFailure("ISO datetime", value));
+      }
+      return Effect.succeed(value);
+    },
+  }),
+
+  nowIsoDateTime: Effect.map(DateTime.now, DateTime.formatIso),
+};

package/src/core/index.ts

@@ -0,0 +1,22 @@
+export { Connector, Cursor, Fetch, Resource } from "./builder";
+export type {
+  ChangesFetch,
+  ConnectorDefinition,
+  Cursor as CursorTypes,
+  FetchChangesResult,
+  FetchPageResult,
+  PageFetch,
+  ResourceBatch,
+  ResourceDefinition,
+  ResourceField,
+  ResourceMutation,
+  ResourcePayload,
+  ResourceRow,
+  ResourceRows,
+  ResourceSchema,
+  ResourceState,
+  WebhookAckMode,
+  WebhookHandler,
+  WebhookRoute,
+  WebhookRouteContext,
+} from "./types";