@useairfoil/connector-kit 0.5.0 → 0.5.2

package/dist/{telemetry-p0dE5Mdu.js → service-DuFiQwid.js}

@@ -1,12 +1,9 @@
 import { t as __export } from "./chunk-Bp6m_JJh.js";
-import { Cause, Config, Context, Effect, Layer, Option } from "effect";
+import { n as PlatformRuntimeKey } from "./constants-BRhIX_rz.js";
+import { Cause, Config, Context, Effect, Layer, Metric, 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,
@@ -17,6 +14,9 @@ var telemetry_exports = /* @__PURE__ */ __export({
 	annotateError: () => annotateError,
 	layer: () => layer,
 	layerConfig: () => layerConfig,
+	layerMetricsConsoleDump: () => layerMetricsConsoleDump,
+	layerOtlp: () => layerOtlp,
+	layerOtlpMetrics: () => layerOtlpMetrics,
 	layerOtlpTracing: () => layerOtlpTracing
 });
 /** Canonical span names emitted by connector-kit runtime instrumentation. */
@@ -51,9 +51,9 @@ 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"))
+	enabled: Config.boolean(PlatformRuntimeKey.otelEnabled).pipe(Config.withDefault(false)),
+	baseUrl: Config.option(Config.string(PlatformRuntimeKey.otelExporterOtlpEndpoint)),
+	rawHeaders: Config.option(Config.string(PlatformRuntimeKey.otelExporterOtlpHeaders))
 });
 const defaultRedactedHeaders = [
 	"authorization",
@@ -165,7 +165,27 @@ const layerOtlpTracing = (options = {}) => Layer.unwrap(Effect.gen(function* ()
 		headers: Option.isSome(raw.rawHeaders) ? parseOtelHeaders(raw.rawHeaders.value) : void 0
 	}, options);
 }));
+const layerOtlpMetrics = (options = {}) => Layer.unwrap(Effect.gen(function* () {
+	const raw = yield* OtlpEnvConfig;
+	if (!raw.enabled) return Layer.empty;
+	const endpoint = Option.getOrUndefined(raw.baseUrl);
+	if (!endpoint) return yield* Effect.fail(/* @__PURE__ */ new Error("OTEL_ENABLED=true requires OTEL_EXPORTER_OTLP_ENDPOINT"));
+	return Observability.OtlpMetrics.layer({
+		url: appendPath(endpoint, "/v1/metrics"),
+		headers: Option.isSome(raw.rawHeaders) ? parseOtelHeaders(raw.rawHeaders.value) : void 0,
+		exportInterval: options.exportInterval,
+		temporality: "cumulative"
+	}).pipe(Layer.provide(Observability.OtlpSerialization.layerJson));
+}));
+const layerOtlp = (options = {}) => Layer.mergeAll(layerOtlpTracing(options), layerOtlpMetrics(options));
+const layerMetricsConsoleDump = (interval = "30 seconds") => Layer.effectDiscard(Effect.gen(function* () {
+	yield* Effect.forkScoped(Effect.forever(Metric.dump.pipe(Effect.flatMap((snapshot) => Effect.logInfo(snapshot)), Effect.andThen(Effect.sleep(interval)))));
+}));
+
+//#endregion
+//#region src/publisher/service.ts
+var Publisher = class extends Context.Service()("@useairfoil/connector-kit/Publisher") {};
 
 //#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
+export { SpanName as a, telemetry_exports as c, EventName as i, Attr as n, addCurrentSpanEvent as o, EventAttr as r, annotateError as s, Publisher as t };
+//# sourceMappingURL=service-DuFiQwid.js.map

package/dist/service-DuFiQwid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-DuFiQwid.js","names":["defaultRedactedHeaders: ReadonlyArray<string | RegExp>"],"sources":["../src/telemetry.ts","../src/publisher/service.ts"],"sourcesContent":["import { Cause, Config, Effect, Layer, Metric, Option, type Duration } from \"effect\";\nimport { Headers } from \"effect/unstable/http\";\nimport * as Observability from \"effect/unstable/observability\";\n\nimport { PlatformRuntimeKey } from \"./runtime-config/constants\";\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(PlatformRuntimeKey.otelEnabled).pipe(Config.withDefault(false)),\n  baseUrl: Config.option(Config.string(PlatformRuntimeKey.otelExporterOtlpEndpoint)),\n  rawHeaders: Config.option(Config.string(PlatformRuntimeKey.otelExporterOtlpHeaders)),\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\nexport type OtlpMetricsOptions = {\n  readonly exportInterval?: Duration.Input;\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\nexport const layerOtlpMetrics = (options: OtlpMetricsOptions = {}) =>\n  Layer.unwrap(\n    Effect.gen(function* () {\n      const raw = yield* OtlpEnvConfig;\n      if (!raw.enabled) return Layer.empty;\n      const endpoint = Option.getOrUndefined(raw.baseUrl);\n      if (!endpoint)\n        return yield* Effect.fail(\n          new Error(\"OTEL_ENABLED=true requires OTEL_EXPORTER_OTLP_ENDPOINT\"),\n        );\n      return Observability.OtlpMetrics.layer({\n        url: appendPath(endpoint, \"/v1/metrics\"),\n        headers: Option.isSome(raw.rawHeaders) ? parseOtelHeaders(raw.rawHeaders.value) : undefined,\n        exportInterval: options.exportInterval,\n        temporality: \"cumulative\",\n      }).pipe(Layer.provide(Observability.OtlpSerialization.layerJson));\n    }),\n  );\n\nexport const layerOtlp = (options: OtlpTracingOptions & OtlpMetricsOptions = {}) =>\n  Layer.mergeAll(layerOtlpTracing(options), layerOtlpMetrics(options));\n\nexport const layerMetricsConsoleDump = (interval: Duration.Input = \"30 seconds\") =>\n  Layer.effectDiscard(\n    Effect.gen(function* () {\n      yield* Effect.forkScoped(\n        Effect.forever(\n          Metric.dump.pipe(\n            Effect.flatMap((snapshot) => Effect.logInfo(snapshot)),\n            Effect.andThen(Effect.sleep(interval)),\n          ),\n        ),\n      );\n    }),\n  );\n","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"],"mappings":"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"}

package/dist/{service-B7g_lHMI.d.ts → service-IE5qaf9x.d.ts}

@@ -1,5 +1,5 @@
-import { t as ConnectorError } from "./index-DyuT2jzP.js";
-import { c as ResourceBatch } from "./types-ZNrA-Dn0.js";
+import { t as ConnectorError } from "./index-D54ySAKn.js";
+import { c as ResourceBatch } from "./types-B35J5YPu.js";
 import { Context } from "effect";
 import * as Wings from "@useairfoil/wings";
 import * as Effect$1 from "effect/Effect";
@@ -29,4 +29,4 @@ declare const Publisher_base: Context.ServiceClass<Publisher, "@useairfoil/conne
 declare class Publisher extends Publisher_base {}
 //#endregion
 export { PublisherService as a, Publisher as i, PublishOptions as n, PublishSource as r, PublishAck as t };
-//# sourceMappingURL=service-B7g_lHMI.d.ts.map
+//# sourceMappingURL=service-IE5qaf9x.d.ts.map

package/dist/state-store/index.d.ts

@@ -1,4 +1,3 @@
-import "../index-DyuT2jzP.js";
-import "../types-ZNrA-Dn0.js";
-import { i as StateStoreService, n as layerMemory, r as StateStore } from "../index-DaNW63Mv.js";
-export { StateStore, StateStoreService, layerMemory };
+import "../index-D54ySAKn.js";
+import { a as StateStoreService, i as StateStore, n as layerSql, r as layerMemory } from "../index-Coh_SkBs.js";
+export { StateStore, StateStoreService, layerMemory, layerSql };

package/dist/state-store/index.js

@@ -1,3 +1,5 @@
-import { n as layerMemory, r as StateStore } from "../state-store-DG_4QpWG.js";
+import "../errors-DHWylqRZ.js";
+import "../constants-BRhIX_rz.js";
+import { n as layerSql, o as StateStore, r as layerMemory } from "../state-store-yl6LiTQ0.js";
 
-export { StateStore, layerMemory };
+export { StateStore, layerMemory, layerSql };

package/dist/state-store-yl6LiTQ0.js

@@ -0,0 +1,198 @@
+import { t as __export } from "./chunk-Bp6m_JJh.js";
+import { t as ConnectorError } from "./errors-DHWylqRZ.js";
+import { n as PlatformRuntimeKey, t as PlatformRuntimeDefault } from "./constants-BRhIX_rz.js";
+import { Config, Context, DateTime, Effect, Layer, Option, Schema } from "effect";
+import { KeyValueStore } from "effect/unstable/persistence";
+import { SqlClient } from "effect/unstable/sql";
+
+//#region src/state-store/service.ts
+/**
+* Effect service used by ingestion and status logic for connector checkpoints.
+* Production provides `layerSql`; sandboxes and tests may provide `layerMemory`.
+*
+* @example
+* ```ts
+* const program = Effect.gen(function* () {
+*   const state = yield* StateStore;
+*   yield* state.setChangesState("orders", { cursor: "next-page" });
+* });
+* ```
+*/
+var StateStore = class extends Context.Service()("@useairfoil/connector-kit/StateStore") {};
+
+//#endregion
+//#region src/state-store/keys.ts
+const resourceComponentKey = (resource, component) => `resource:${resource}:${component}`;
+const resourceErrorKey = (resource, source) => resourceComponentKey(resource, `error:${source}`);
+/**
+* Prefix for all state owned by one connector instance. The platform-owned ID
+* stays visible so operators can inspect and clean up shared-table rows directly.
+*
+* @example
+* ```ts
+* connectorInstanceKeyPrefix("team-a/orders");
+* // "connector-instance:team-a/orders:"
+* ```
+*/
+const connectorInstanceKeyPrefix = (connectorInstanceId) => `connector-instance:${connectorInstanceId}:`;
+
+//#endregion
+//#region src/state-store/schema.ts
+const CursorValueSchema = Schema.Union([Schema.String, Schema.Number]);
+/** Durable progress for a finite historical backfill. */
+const BackfillStateSchema = Schema.Struct({
+	cutoff: CursorValueSchema,
+	pageCursor: Schema.optional(CursorValueSchema),
+	completed: Schema.Boolean,
+	lastSuccessAt: Schema.optional(Schema.String)
+});
+/** Durable cursor for an ongoing incremental changes stream. */
+const ChangesStateSchema = Schema.Struct({
+	cursor: CursorValueSchema,
+	lastSuccessAt: Schema.optional(Schema.String)
+});
+const StateSourceSchema = Schema.Literals(["backfill", "changes"]);
+const StateOperationSchema = Schema.Literals([
+	"fetch",
+	"publish",
+	"checkpoint"
+]);
+const StateErrorCodeSchema = Schema.Literals([
+	"fetch_failed",
+	"publish_failed",
+	"checkpoint_failed"
+]);
+/** SDK-owned error context safe to persist and expose through status. */
+const ResourceErrorContextSchema = Schema.Struct({
+	source: StateSourceSchema,
+	operation: StateOperationSchema,
+	code: StateErrorCodeSchema,
+	message: Schema.String
+});
+/** Stable public error summary persisted for status reporting; never a raw cause. */
+const ResourceErrorSchema = Schema.Struct({
+	...ResourceErrorContextSchema.fields,
+	at: Schema.String
+});
+/** Complete persisted state assembled from independently stored components. */
+const ResourceStateSchema = Schema.Struct({
+	backfill: Schema.optional(BackfillStateSchema),
+	changes: Schema.optional(ChangesStateSchema),
+	lastError: Schema.optional(ResourceErrorSchema)
+});
+
+//#endregion
+//#region src/state-store/layer-key-value-store.ts
+const mapStoreError = (operation, resource) => Effect.mapError((cause) => new ConnectorError({
+	message: `Failed to ${operation} state for resource ${resource}`,
+	cause
+}));
+const resourceErrorContext = (source, operation) => {
+	const sourceName = source === "backfill" ? "Backfill" : "Changes";
+	switch (operation) {
+		case "fetch": return {
+			source,
+			operation,
+			code: "fetch_failed",
+			message: `${sourceName} fetch failed`
+		};
+		case "publish": return {
+			source,
+			operation,
+			code: "publish_failed",
+			message: `${sourceName} publish failed`
+		};
+		case "checkpoint": return {
+			source,
+			operation,
+			code: "checkpoint_failed",
+			message: `${sourceName} checkpoint failed`
+		};
+	}
+};
+const latestError = (backfill, changes) => {
+	if (Option.isNone(backfill)) return changes;
+	if (Option.isNone(changes)) return backfill;
+	return backfill.value.at >= changes.value.at ? backfill : changes;
+};
+/**
+* Implements StateStore over any Effect KeyValueStore. `toSchemaStore` owns
+* serialization and validates persisted values when they are read and written.
+* The caller owns instance scoping; `layerSql` supplies the production prefix.
+*/
+const layerKeyValueStore = Layer.effect(StateStore)(Effect.gen(function* () {
+	const keyValueStore = yield* KeyValueStore.KeyValueStore;
+	const backfillStore = KeyValueStore.toSchemaStore(keyValueStore, BackfillStateSchema);
+	const changesStore = KeyValueStore.toSchemaStore(keyValueStore, ChangesStateSchema);
+	const errorStore = KeyValueStore.toSchemaStore(keyValueStore, ResourceErrorSchema);
+	const getResourceState = (resource) => Effect.all({
+		backfill: backfillStore.get(resourceComponentKey(resource, "backfill")),
+		changes: changesStore.get(resourceComponentKey(resource, "changes")),
+		backfillError: errorStore.get(resourceErrorKey(resource, "backfill")),
+		changesError: errorStore.get(resourceErrorKey(resource, "changes"))
+	}, { concurrency: "unbounded" }).pipe(Effect.map(({ backfill, changes, backfillError, changesError }) => {
+		const lastError = latestError(backfillError, changesError);
+		if (Option.isNone(backfill) && Option.isNone(changes) && Option.isNone(lastError)) return;
+		return {
+			...Option.isSome(backfill) ? { backfill: backfill.value } : {},
+			...Option.isSome(changes) ? { changes: changes.value } : {},
+			...Option.isSome(lastError) ? { lastError: lastError.value } : {}
+		};
+	}), mapStoreError("read", resource));
+	const setBackfillState = (resource, state) => backfillStore.set(resourceComponentKey(resource, "backfill"), state).pipe(mapStoreError("write", resource));
+	const setChangesState = (resource, state) => changesStore.set(resourceComponentKey(resource, "changes"), state).pipe(mapStoreError("write", resource));
+	const setResourceError = (resource, source, operation) => DateTime.now.pipe(Effect.map(DateTime.formatIso), Effect.flatMap((at) => {
+		const error = resourceErrorContext(source, operation);
+		return errorStore.set(resourceErrorKey(resource, source), {
+			...error,
+			at
+		});
+	}), mapStoreError("write", resource));
+	const clearResourceError = (resource, source) => errorStore.remove(resourceErrorKey(resource, source)).pipe(mapStoreError("clear", resource));
+	return StateStore.of({
+		getResourceState,
+		setBackfillState,
+		setChangesState,
+		setResourceError,
+		clearResourceError
+	});
+}));
+
+//#endregion
+//#region src/state-store/layer-memory.ts
+/** Process-local state for tests and explicit local sandbox commands. */
+const layerMemory = layerKeyValueStore.pipe(Layer.provide(KeyValueStore.layerMemory));
+
+//#endregion
+//#region src/state-store/layer-sql.ts
+const scopedKeyValueStore = (connectorInstanceId) => Layer.effect(KeyValueStore.KeyValueStore)(KeyValueStore.KeyValueStore.pipe(Effect.map(KeyValueStore.prefix(connectorInstanceKeyPrefix(connectorInstanceId)))));
+/**
+* Shared SQL state using the immutable connector instance ID supplied by
+* platform-owned Effect configuration. The table defaults to
+* `_airfoil_connectors_state` and can be overridden with `AIRFOIL_STATE_TABLE`.
+* Effect's SQL KeyValueStore owns the table, while `KeyValueStore.prefix`
+* provides application-level isolation between connector instances in that
+* table. The resulting layer exposes only StateStore, never the unscoped
+* KeyValueStore.
+*
+* @example
+* ```ts
+* const StateStoreLive = layerSql().pipe(Layer.provide(PostgresLive));
+* ```
+*/
+const layerSql = () => Layer.unwrap(Config.all({
+	connectorInstanceId: Config.nonEmptyString(PlatformRuntimeKey.connectorInstanceId),
+	table: Config.nonEmptyString(PlatformRuntimeKey.stateTable).pipe(Config.withDefault(PlatformRuntimeDefault.stateTable))
+}).pipe(Effect.map(({ connectorInstanceId, table }) => layerKeyValueStore.pipe(Layer.provide(scopedKeyValueStore(connectorInstanceId).pipe(Layer.provide(KeyValueStore.layerSql({ table }))))))));
+
+//#endregion
+//#region src/state-store/index.ts
+var state_store_exports = /* @__PURE__ */ __export({
+	StateStore: () => StateStore,
+	layerMemory: () => layerMemory,
+	layerSql: () => layerSql
+});
+
+//#endregion
+export { ResourceStateSchema as a, ResourceErrorSchema as i, layerSql as n, StateStore as o, layerMemory as r, state_store_exports as t };
+//# sourceMappingURL=state-store-yl6LiTQ0.js.map

package/dist/state-store-yl6LiTQ0.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-store-yl6LiTQ0.js","names":["layerKeyValueStore: Layer.Layer<StateStore, never, KeyValueStore.KeyValueStore>","layerMemory: Layer.Layer<StateStore>"],"sources":["../src/state-store/service.ts","../src/state-store/keys.ts","../src/state-store/schema.ts","../src/state-store/layer-key-value-store.ts","../src/state-store/layer-memory.ts","../src/state-store/layer-sql.ts","../src/state-store/index.ts"],"sourcesContent":["import { Context, Effect } from \"effect\";\n\nimport type {\n  PersistedBackfillState,\n  PersistedChangesState,\n  PersistedResourceState,\n  StateOperation,\n  StateSource,\n} from \"./schema\";\n\nimport { ConnectorError } from \"../errors\";\n\n/** Connector-facing durable state operations, independent of the storage backend. */\nexport interface StateStoreService {\n  readonly getResourceState: (\n    resource: string,\n  ) => Effect.Effect<PersistedResourceState | undefined, ConnectorError>;\n  readonly setBackfillState: (\n    resource: string,\n    state: PersistedBackfillState,\n  ) => Effect.Effect<void, ConnectorError>;\n  readonly setChangesState: (\n    resource: string,\n    state: PersistedChangesState,\n  ) => Effect.Effect<void, ConnectorError>;\n  readonly setResourceError: (\n    resource: string,\n    source: StateSource,\n    operation: StateOperation,\n  ) => Effect.Effect<void, ConnectorError>;\n  readonly clearResourceError: (\n    resource: string,\n    source: StateSource,\n  ) => Effect.Effect<void, ConnectorError>;\n}\n\n/**\n * Effect service used by ingestion and status logic for connector checkpoints.\n * Production provides `layerSql`; sandboxes and tests may provide `layerMemory`.\n *\n * @example\n * ```ts\n * const program = Effect.gen(function* () {\n *   const state = yield* StateStore;\n *   yield* state.setChangesState(\"orders\", { cursor: \"next-page\" });\n * });\n * ```\n */\nexport class StateStore extends Context.Service<StateStore, StateStoreService>()(\n  \"@useairfoil/connector-kit/StateStore\",\n) {}\n","import type { StateSource } from \"./schema\";\n\ntype StateComponent = StateSource | `error:${StateSource}`;\n\nexport const resourceComponentKey = (resource: string, component: StateComponent): string =>\n  `resource:${resource}:${component}`;\n\nexport const resourceErrorKey = (resource: string, source: StateSource): string =>\n  resourceComponentKey(resource, `error:${source}`);\n\n/**\n * Prefix for all state owned by one connector instance. The platform-owned ID\n * stays visible so operators can inspect and clean up shared-table rows directly.\n *\n * @example\n * ```ts\n * connectorInstanceKeyPrefix(\"team-a/orders\");\n * // \"connector-instance:team-a/orders:\"\n * ```\n */\nexport const connectorInstanceKeyPrefix = (connectorInstanceId: string): string =>\n  `connector-instance:${connectorInstanceId}:`;\n","import { Schema } from \"effect\";\n\nconst CursorValueSchema = Schema.Union([Schema.String, Schema.Number]);\n\n/** Durable progress for a finite historical backfill. */\nexport const BackfillStateSchema = Schema.Struct({\n  cutoff: CursorValueSchema,\n  pageCursor: Schema.optional(CursorValueSchema),\n  completed: Schema.Boolean,\n  lastSuccessAt: Schema.optional(Schema.String),\n});\n\n/** Durable cursor for an ongoing incremental changes stream. */\nexport const ChangesStateSchema = Schema.Struct({\n  cursor: CursorValueSchema,\n  lastSuccessAt: Schema.optional(Schema.String),\n});\n\nexport const StateSourceSchema = Schema.Literals([\"backfill\", \"changes\"]);\n\nexport const StateOperationSchema = Schema.Literals([\"fetch\", \"publish\", \"checkpoint\"]);\n\nexport const StateErrorCodeSchema = Schema.Literals([\n  \"fetch_failed\",\n  \"publish_failed\",\n  \"checkpoint_failed\",\n]);\n\n/** SDK-owned error context safe to persist and expose through status. */\nexport const ResourceErrorContextSchema = Schema.Struct({\n  source: StateSourceSchema,\n  operation: StateOperationSchema,\n  code: StateErrorCodeSchema,\n  message: Schema.String,\n});\n\n/** Stable public error summary persisted for status reporting; never a raw cause. */\nexport const ResourceErrorSchema = Schema.Struct({\n  ...ResourceErrorContextSchema.fields,\n  at: Schema.String,\n});\n\n/** Complete persisted state assembled from independently stored components. */\nexport const ResourceStateSchema = Schema.Struct({\n  backfill: Schema.optional(BackfillStateSchema),\n  changes: Schema.optional(ChangesStateSchema),\n  lastError: Schema.optional(ResourceErrorSchema),\n});\n\nexport type PersistedBackfillState = Schema.Schema.Type<typeof BackfillStateSchema>;\nexport type PersistedChangesState = Schema.Schema.Type<typeof ChangesStateSchema>;\nexport type StateSource = Schema.Schema.Type<typeof StateSourceSchema>;\nexport type StateOperation = Schema.Schema.Type<typeof StateOperationSchema>;\nexport type StateErrorCode = Schema.Schema.Type<typeof StateErrorCodeSchema>;\nexport type ResourceErrorContext = Schema.Schema.Type<typeof ResourceErrorContextSchema>;\nexport type PersistedResourceError = Schema.Schema.Type<typeof ResourceErrorSchema>;\nexport type PersistedResourceState = Schema.Schema.Type<typeof ResourceStateSchema>;\n","import { DateTime, Effect, Layer, Option, Schema } from \"effect\";\nimport { KeyValueStore } from \"effect/unstable/persistence\";\n\nimport { ConnectorError } from \"../errors\";\nimport { resourceComponentKey, resourceErrorKey } from \"./keys\";\nimport {\n  BackfillStateSchema,\n  ChangesStateSchema,\n  ResourceErrorSchema,\n  type PersistedBackfillState,\n  type PersistedChangesState,\n  type PersistedResourceError,\n  type ResourceErrorContext,\n  type StateOperation,\n  type StateSource,\n} from \"./schema\";\nimport { StateStore } from \"./service\";\n\nconst mapStoreError = (operation: \"read\" | \"write\" | \"clear\", resource: string) =>\n  Effect.mapError(\n    (cause: KeyValueStore.KeyValueStoreError | Schema.SchemaError) =>\n      new ConnectorError({\n        message: `Failed to ${operation} state for resource ${resource}`,\n        cause,\n      }),\n  );\n\nconst resourceErrorContext = (\n  source: StateSource,\n  operation: StateOperation,\n): ResourceErrorContext => {\n  const sourceName = source === \"backfill\" ? \"Backfill\" : \"Changes\";\n  switch (operation) {\n    case \"fetch\":\n      return { source, operation, code: \"fetch_failed\", message: `${sourceName} fetch failed` };\n    case \"publish\":\n      return { source, operation, code: \"publish_failed\", message: `${sourceName} publish failed` };\n    case \"checkpoint\":\n      return {\n        source,\n        operation,\n        code: \"checkpoint_failed\",\n        message: `${sourceName} checkpoint failed`,\n      };\n  }\n};\n\nconst latestError = (\n  backfill: Option.Option<PersistedResourceError>,\n  changes: Option.Option<PersistedResourceError>,\n): Option.Option<PersistedResourceError> => {\n  if (Option.isNone(backfill)) return changes;\n  if (Option.isNone(changes)) return backfill;\n  return backfill.value.at >= changes.value.at ? backfill : changes;\n};\n\n/**\n * Implements StateStore over any Effect KeyValueStore. `toSchemaStore` owns\n * serialization and validates persisted values when they are read and written.\n * The caller owns instance scoping; `layerSql` supplies the production prefix.\n */\nexport const layerKeyValueStore: Layer.Layer<StateStore, never, KeyValueStore.KeyValueStore> =\n  Layer.effect(StateStore)(\n    Effect.gen(function* () {\n      const keyValueStore = yield* KeyValueStore.KeyValueStore;\n      const backfillStore = KeyValueStore.toSchemaStore(keyValueStore, BackfillStateSchema);\n      const changesStore = KeyValueStore.toSchemaStore(keyValueStore, ChangesStateSchema);\n      const errorStore = KeyValueStore.toSchemaStore(keyValueStore, ResourceErrorSchema);\n\n      const getResourceState = (resource: string) =>\n        // Components use separate keys so a cursor update cannot overwrite the\n        // independently managed error or backfill state.\n        Effect.all(\n          {\n            backfill: backfillStore.get(resourceComponentKey(resource, \"backfill\")),\n            changes: changesStore.get(resourceComponentKey(resource, \"changes\")),\n            backfillError: errorStore.get(resourceErrorKey(resource, \"backfill\")),\n            changesError: errorStore.get(resourceErrorKey(resource, \"changes\")),\n          },\n          { concurrency: \"unbounded\" },\n        ).pipe(\n          Effect.map(({ backfill, changes, backfillError, changesError }) => {\n            const lastError = latestError(backfillError, changesError);\n            if (Option.isNone(backfill) && Option.isNone(changes) && Option.isNone(lastError)) {\n              return undefined;\n            }\n            return {\n              ...(Option.isSome(backfill) ? { backfill: backfill.value } : {}),\n              ...(Option.isSome(changes) ? { changes: changes.value } : {}),\n              ...(Option.isSome(lastError) ? { lastError: lastError.value } : {}),\n            };\n          }),\n          mapStoreError(\"read\", resource),\n        );\n\n      const setBackfillState = (resource: string, state: PersistedBackfillState) =>\n        backfillStore\n          .set(resourceComponentKey(resource, \"backfill\"), state)\n          .pipe(mapStoreError(\"write\", resource));\n\n      const setChangesState = (resource: string, state: PersistedChangesState) =>\n        changesStore\n          .set(resourceComponentKey(resource, \"changes\"), state)\n          .pipe(mapStoreError(\"write\", resource));\n\n      const setResourceError = (resource: string, source: StateSource, operation: StateOperation) =>\n        DateTime.now.pipe(\n          Effect.map(DateTime.formatIso),\n          Effect.flatMap((at) => {\n            const error = resourceErrorContext(source, operation);\n            return errorStore.set(resourceErrorKey(resource, source), {\n              ...error,\n              at,\n            });\n          }),\n          mapStoreError(\"write\", resource),\n        );\n\n      const clearResourceError = (resource: string, source: StateSource) =>\n        errorStore\n          .remove(resourceErrorKey(resource, source))\n          .pipe(mapStoreError(\"clear\", resource));\n\n      return StateStore.of({\n        getResourceState,\n        setBackfillState,\n        setChangesState,\n        setResourceError,\n        clearResourceError,\n      });\n    }),\n  );\n","import { Layer } from \"effect\";\nimport { KeyValueStore } from \"effect/unstable/persistence\";\n\nimport type { StateStore } from \"./service\";\n\nimport { layerKeyValueStore } from \"./layer-key-value-store\";\n\n/** Process-local state for tests and explicit local sandbox commands. */\nexport const layerMemory: Layer.Layer<StateStore> = layerKeyValueStore.pipe(\n  Layer.provide(KeyValueStore.layerMemory),\n);\n","import { Config, Effect, Layer } from \"effect\";\nimport { KeyValueStore } from \"effect/unstable/persistence\";\nimport { SqlClient } from \"effect/unstable/sql\";\n\nimport type { StateStore } from \"./service\";\n\nimport { PlatformRuntimeDefault, PlatformRuntimeKey } from \"../runtime-config/constants\";\nimport { connectorInstanceKeyPrefix } from \"./keys\";\nimport { layerKeyValueStore } from \"./layer-key-value-store\";\n\nconst scopedKeyValueStore = (connectorInstanceId: string) =>\n  Layer.effect(KeyValueStore.KeyValueStore)(\n    KeyValueStore.KeyValueStore.pipe(\n      Effect.map(KeyValueStore.prefix(connectorInstanceKeyPrefix(connectorInstanceId))),\n    ),\n  );\n\n/**\n * Shared SQL state using the immutable connector instance ID supplied by\n * platform-owned Effect configuration. The table defaults to\n * `_airfoil_connectors_state` and can be overridden with `AIRFOIL_STATE_TABLE`.\n * Effect's SQL KeyValueStore owns the table, while `KeyValueStore.prefix`\n * provides application-level isolation between connector instances in that\n * table. The resulting layer exposes only StateStore, never the unscoped\n * KeyValueStore.\n *\n * @example\n * ```ts\n * const StateStoreLive = layerSql().pipe(Layer.provide(PostgresLive));\n * ```\n */\nexport const layerSql = (): Layer.Layer<StateStore, Config.ConfigError, SqlClient.SqlClient> =>\n  Layer.unwrap(\n    Config.all({\n      connectorInstanceId: Config.nonEmptyString(PlatformRuntimeKey.connectorInstanceId),\n      table: Config.nonEmptyString(PlatformRuntimeKey.stateTable).pipe(\n        Config.withDefault(PlatformRuntimeDefault.stateTable),\n      ),\n    }).pipe(\n      Effect.map(({ connectorInstanceId, table }) =>\n        layerKeyValueStore.pipe(\n          Layer.provide(\n            scopedKeyValueStore(connectorInstanceId).pipe(\n              Layer.provide(KeyValueStore.layerSql({ table })),\n            ),\n          ),\n        ),\n      ),\n    ),\n  );\n","export { StateStore, type StateStoreService } from \"./service\";\nexport { layerMemory } from \"./layer-memory\";\nexport { layerSql } from \"./layer-sql\";\n"],"mappings":"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"}

package/dist/status/index.d.ts

@@ -0,0 +1,5 @@
+import "../index-D54ySAKn.js";
+import "../types-B35J5YPu.js";
+import "../index-Coh_SkBs.js";
+import { a as ResourceStatusSchema, c as StatusUnavailableResponse, d as SyncStateSchema, f as statusRoute, i as ResourceStatus, l as StatusUnavailableResponseSchema, n as ResourceError, o as StatusResponse, r as ResourceErrorSchema, s as StatusResponseSchema, u as SyncState } from "../index-Cq2IzY7T.js";
+export { ResourceError, ResourceErrorSchema, ResourceStatus, ResourceStatusSchema, StatusResponse, StatusResponseSchema, StatusUnavailableResponse, StatusUnavailableResponseSchema, SyncState, SyncStateSchema, statusRoute };

package/dist/status/index.js

@@ -0,0 +1,6 @@
+import "../errors-DHWylqRZ.js";
+import "../constants-BRhIX_rz.js";
+import "../state-store-yl6LiTQ0.js";
+import { a as StatusUnavailableResponseSchema, i as StatusResponseSchema, n as ResourceErrorSchema, o as SyncStateSchema, r as ResourceStatusSchema, s as statusRoute } from "../status-B-oZBc33.js";
+
+export { ResourceErrorSchema, ResourceStatusSchema, StatusResponseSchema, StatusUnavailableResponseSchema, SyncStateSchema, statusRoute };

package/dist/status-B-oZBc33.js

@@ -0,0 +1,84 @@
+import { t as __export } from "./chunk-Bp6m_JJh.js";
+import { a as ResourceStateSchema, i as ResourceErrorSchema, o as StateStore } from "./state-store-yl6LiTQ0.js";
+import { Cause, Effect, Schema } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
+
+//#region src/state-store/state.ts
+/** Normalizes a cursor value to its persisted/wire representation (never a Date). */
+const normalizeCursor = (value) => value instanceof Date ? value.toISOString() : value;
+/** Derives connector-facing sync state from durable state and resource capabilities. */
+const deriveSyncState = (resource, state) => {
+	if (state?.lastError) return "error";
+	if (!resource.backfill && !resource.changes) return "live";
+	if (!state) return "pending";
+	if (resource.backfill && (!state.backfill || !state.backfill.completed)) return "backfilling";
+	return "live";
+};
+
+//#endregion
+//#region src/status/route.ts
+const statusRoute = (connector, path = "/status") => HttpRouter.add("GET", path, Effect.gen(function* () {
+	const store = yield* StateStore;
+	const resources = yield* Effect.forEach(connector.resources, (resource) => store.getResourceState(resource.name).pipe(Effect.map((state) => ({
+		name: resource.name,
+		state: deriveSyncState(resource, state),
+		...state?.backfill ? { backfill: {
+			completed: state.backfill.completed,
+			cutoff: normalizeCursor(state.backfill.cutoff),
+			...state.backfill.pageCursor !== void 0 ? { pageCursor: normalizeCursor(state.backfill.pageCursor) } : {},
+			...state.backfill.lastSuccessAt !== void 0 ? { lastSuccessAt: state.backfill.lastSuccessAt } : {}
+		} } : {},
+		...state?.changes ? { changes: {
+			cursor: normalizeCursor(state.changes.cursor),
+			...state.changes.lastSuccessAt !== void 0 ? { lastSuccessAt: state.changes.lastSuccessAt } : {}
+		} } : {},
+		...state?.lastError ? { lastError: state.lastError } : {}
+	}))), { concurrency: "unbounded" });
+	return HttpServerResponse.jsonUnsafe({
+		connector: connector.name,
+		resources
+	});
+}).pipe(Effect.catchCause((cause) => Effect.logWarning(`Status route failed: ${Cause.pretty(cause)}`).pipe(Effect.andThen(Effect.succeed(HttpServerResponse.jsonUnsafe({
+	ok: false,
+	error: "Failed to compute status"
+}, { status: 500 })))))));
+
+//#endregion
+//#region src/status/types.ts
+const SyncStateSchema = Schema.Literals([
+	"pending",
+	"backfilling",
+	"live",
+	"error"
+]);
+/** Safe source failure returned by the status endpoint. */
+const ResourceErrorSchema$1 = ResourceErrorSchema;
+const ResourceStatusSchema = Schema.Struct({
+	name: Schema.String,
+	state: SyncStateSchema,
+	...ResourceStateSchema.fields
+});
+const StatusResponseSchema = Schema.Struct({
+	connector: Schema.String,
+	resources: Schema.Array(ResourceStatusSchema)
+});
+/** Returned when durable resource status cannot be read. */
+const StatusUnavailableResponseSchema = Schema.Struct({
+	ok: Schema.Literal(false),
+	error: Schema.String
+});
+
+//#endregion
+//#region src/status/index.ts
+var status_exports = /* @__PURE__ */ __export({
+	ResourceErrorSchema: () => ResourceErrorSchema$1,
+	ResourceStatusSchema: () => ResourceStatusSchema,
+	StatusResponseSchema: () => StatusResponseSchema,
+	StatusUnavailableResponseSchema: () => StatusUnavailableResponseSchema,
+	SyncStateSchema: () => SyncStateSchema,
+	statusRoute: () => statusRoute
+});
+
+//#endregion
+export { StatusUnavailableResponseSchema as a, deriveSyncState as c, StatusResponseSchema as i, normalizeCursor as l, ResourceErrorSchema$1 as n, SyncStateSchema as o, ResourceStatusSchema as r, statusRoute as s, status_exports as t };
+//# sourceMappingURL=status-B-oZBc33.js.map

package/dist/status-B-oZBc33.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-B-oZBc33.js","names":["ResourceErrorSchema","StateResourceErrorSchema"],"sources":["../src/state-store/state.ts","../src/status/route.ts","../src/status/types.ts","../src/status/index.ts"],"sourcesContent":["import type { Cursor, ResourceDefinition, ResourceState, SyncState } from \"../core/types\";\n\n/** Normalizes a cursor value to its persisted/wire representation (never a Date). */\nexport const normalizeCursor = (value: Cursor.Value): string | number =>\n  value instanceof Date ? value.toISOString() : value;\n\n/** Derives connector-facing sync state from durable state and resource capabilities. */\nexport const deriveSyncState = (\n  resource: ResourceDefinition,\n  state: ResourceState | undefined,\n): SyncState => {\n  if (state?.lastError) return \"error\";\n  if (!resource.backfill && !resource.changes) return \"live\";\n  if (!state) return \"pending\";\n  if (resource.backfill && (!state.backfill || !state.backfill.completed)) return \"backfilling\";\n  return \"live\";\n};\n","import { Cause, Effect } from \"effect\";\nimport { HttpRouter, HttpServerResponse } from \"effect/unstable/http\";\n\nimport type { ConnectorDefinition } from \"../core/types\";\nimport type { ResourceStatus, StatusUnavailableResponse } from \"./types\";\n\nimport { StateStore } from \"../state-store\";\nimport { deriveSyncState, normalizeCursor } from \"../state-store/state\";\n\nexport const statusRoute = (\n  connector: ConnectorDefinition,\n  path: HttpRouter.PathInput = \"/status\",\n) =>\n  HttpRouter.add(\n    \"GET\",\n    path,\n    Effect.gen(function* () {\n      const store = yield* StateStore;\n\n      const resources = yield* Effect.forEach(\n        connector.resources,\n        (resource) =>\n          store.getResourceState(resource.name).pipe(\n            Effect.map(\n              (state): ResourceStatus => ({\n                name: resource.name,\n                state: deriveSyncState(resource, state),\n                ...(state?.backfill\n                  ? {\n                      backfill: {\n                        completed: state.backfill.completed,\n                        cutoff: normalizeCursor(state.backfill.cutoff),\n                        ...(state.backfill.pageCursor !== undefined\n                          ? { pageCursor: normalizeCursor(state.backfill.pageCursor) }\n                          : {}),\n                        ...(state.backfill.lastSuccessAt !== undefined\n                          ? { lastSuccessAt: state.backfill.lastSuccessAt }\n                          : {}),\n                      },\n                    }\n                  : {}),\n                ...(state?.changes\n                  ? {\n                      changes: {\n                        cursor: normalizeCursor(state.changes.cursor),\n                        ...(state.changes.lastSuccessAt !== undefined\n                          ? { lastSuccessAt: state.changes.lastSuccessAt }\n                          : {}),\n                      },\n                    }\n                  : {}),\n                ...(state?.lastError ? { lastError: state.lastError } : {}),\n              }),\n            ),\n          ),\n        { concurrency: \"unbounded\" },\n      );\n\n      return HttpServerResponse.jsonUnsafe({ connector: connector.name, resources });\n    }).pipe(\n      Effect.catchCause((cause) =>\n        Effect.logWarning(`Status route failed: ${Cause.pretty(cause)}`).pipe(\n          Effect.andThen(\n            Effect.succeed(\n              HttpServerResponse.jsonUnsafe(\n                {\n                  ok: false,\n                  error: \"Failed to compute status\",\n                } satisfies StatusUnavailableResponse,\n                { status: 500 },\n              ),\n            ),\n          ),\n        ),\n      ),\n    ),\n  );\n","import { Schema } from \"effect\";\n\nimport {\n  ResourceErrorSchema as StateResourceErrorSchema,\n  ResourceStateSchema,\n} from \"../state-store/schema\";\n\nexport const SyncStateSchema = Schema.Literals([\"pending\", \"backfilling\", \"live\", \"error\"]);\nexport type SyncState = Schema.Schema.Type<typeof SyncStateSchema>;\n\n/** Safe source failure returned by the status endpoint. */\nexport const ResourceErrorSchema = StateResourceErrorSchema;\nexport type ResourceError = Schema.Schema.Type<typeof ResourceErrorSchema>;\n\nexport const ResourceStatusSchema = Schema.Struct({\n  name: Schema.String,\n  state: SyncStateSchema,\n  ...ResourceStateSchema.fields,\n});\nexport type ResourceStatus = Schema.Schema.Type<typeof ResourceStatusSchema>;\n\nexport const StatusResponseSchema = Schema.Struct({\n  connector: Schema.String,\n  resources: Schema.Array(ResourceStatusSchema),\n});\nexport type StatusResponse = Schema.Schema.Type<typeof StatusResponseSchema>;\n\n/** Returned when durable resource status cannot be read. */\nexport const StatusUnavailableResponseSchema = Schema.Struct({\n  ok: Schema.Literal(false),\n  error: Schema.String,\n});\nexport type StatusUnavailableResponse = Schema.Schema.Type<typeof StatusUnavailableResponseSchema>;\n","export * from \"./route\";\nexport * from \"./types\";\n"],"mappings":";;;;;;;AAGA,MAAa,mBAAmB,UAC9B,iBAAiB,OAAO,MAAM,aAAa,GAAG;;AAGhD,MAAa,mBACX,UACA,UACc;AACd,KAAI,OAAO,UAAW,QAAO;AAC7B,KAAI,CAAC,SAAS,YAAY,CAAC,SAAS,QAAS,QAAO;AACpD,KAAI,CAAC,MAAO,QAAO;AACnB,KAAI,SAAS,aAAa,CAAC,MAAM,YAAY,CAAC,MAAM,SAAS,WAAY,QAAO;AAChF,QAAO;;;;;ACNT,MAAa,eACX,WACA,OAA6B,cAE7B,WAAW,IACT,OACA,MACA,OAAO,IAAI,aAAa;CACtB,MAAM,QAAQ,OAAO;CAErB,MAAM,YAAY,OAAO,OAAO,QAC9B,UAAU,YACT,aACC,MAAM,iBAAiB,SAAS,KAAK,CAAC,KACpC,OAAO,KACJ,WAA2B;EAC1B,MAAM,SAAS;EACf,OAAO,gBAAgB,UAAU,MAAM;EACvC,GAAI,OAAO,WACP,EACE,UAAU;GACR,WAAW,MAAM,SAAS;GAC1B,QAAQ,gBAAgB,MAAM,SAAS,OAAO;GAC9C,GAAI,MAAM,SAAS,eAAe,SAC9B,EAAE,YAAY,gBAAgB,MAAM,SAAS,WAAW,EAAE,GAC1D,EAAE;GACN,GAAI,MAAM,SAAS,kBAAkB,SACjC,EAAE,eAAe,MAAM,SAAS,eAAe,GAC/C,EAAE;GACP,EACF,GACD,EAAE;EACN,GAAI,OAAO,UACP,EACE,SAAS;GACP,QAAQ,gBAAgB,MAAM,QAAQ,OAAO;GAC7C,GAAI,MAAM,QAAQ,kBAAkB,SAChC,EAAE,eAAe,MAAM,QAAQ,eAAe,GAC9C,EAAE;GACP,EACF,GACD,EAAE;EACN,GAAI,OAAO,YAAY,EAAE,WAAW,MAAM,WAAW,GAAG,EAAE;EAC3D,EACF,CACF,EACH,EAAE,aAAa,aAAa,CAC7B;AAED,QAAO,mBAAmB,WAAW;EAAE,WAAW,UAAU;EAAM;EAAW,CAAC;EAC9E,CAAC,KACD,OAAO,YAAY,UACjB,OAAO,WAAW,wBAAwB,MAAM,OAAO,MAAM,GAAG,CAAC,KAC/D,OAAO,QACL,OAAO,QACL,mBAAmB,WACjB;CACE,IAAI;CACJ,OAAO;CACR,EACD,EAAE,QAAQ,KAAK,CAChB,CACF,CACF,CACF,CACF,CACF,CACF;;;;ACrEH,MAAa,kBAAkB,OAAO,SAAS;CAAC;CAAW;CAAe;CAAQ;CAAQ,CAAC;;AAI3F,MAAaA,wBAAsBC;AAGnC,MAAa,uBAAuB,OAAO,OAAO;CAChD,MAAM,OAAO;CACb,OAAO;CACP,GAAG,oBAAoB;CACxB,CAAC;AAGF,MAAa,uBAAuB,OAAO,OAAO;CAChD,WAAW,OAAO;CAClB,WAAW,OAAO,MAAM,qBAAqB;CAC9C,CAAC;;AAIF,MAAa,kCAAkC,OAAO,OAAO;CAC3D,IAAI,OAAO,QAAQ,MAAM;CACzB,OAAO,OAAO;CACf,CAAC"}

package/dist/{types-ZNrA-Dn0.d.ts → types-B35J5YPu.d.ts}

@@ -1,4 +1,4 @@
-import { t as ConnectorError } from "./index-DyuT2jzP.js";
+import { t as ConnectorError } from "./index-D54ySAKn.js";
 import { Duration, Effect, Schema } from "effect";
 import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 
@@ -29,11 +29,21 @@ type ResourceState = {
     readonly cutoff: Cursor.Value;
     readonly pageCursor?: Cursor.Value;
     readonly completed: boolean;
+    readonly lastSuccessAt?: string;
   };
   readonly changes?: {
     readonly cursor: Cursor.Value;
+    readonly lastSuccessAt?: string;
+  };
+  readonly lastError?: {
+    readonly source: "backfill" | "changes";
+    readonly operation: "fetch" | "publish" | "checkpoint";
+    readonly code: "fetch_failed" | "publish_failed" | "checkpoint_failed";
+    readonly message: string;
+    readonly at: string;
   };
 };
+type SyncState = "pending" | "backfilling" | "live" | "error";
 type ResourceSchema = Schema.Decoder<object>;
 /**
  * Takes a resource schema and returns its decoded row object type.
@@ -91,14 +101,16 @@ type WebhookHandler<Row extends object, Payload$1> = {
     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;
+type ResourceDefinition<S$1 extends ResourceSchema = ResourceSchema, Payload$1 = unknown, R = never, Name extends string = string> = {
+  readonly name: Name;
   readonly schema: S$1;
   readonly key: ResourceField<NoInfer<S$1>>;
   readonly version: ResourceField<NoInfer<S$1>>;
   readonly partition?: {
     readonly required: boolean;
   };
+  /** Read-only validation used before provisioning this resource. */
+  readonly check: Effect.Effect<void, ConnectorError>;
   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>;
@@ -122,6 +134,8 @@ type ResourceDefinition<S$1 extends ResourceSchema = ResourceSchema, Payload$1 =
  * ```
  */
 type ResourceRows<Resources extends ReadonlyArray<ResourceDefinition>> = { readonly [Resource in Resources[number] as Resource["name"]]: Resource extends ResourceDefinition<infer S, unknown, unknown> ? ResourceRow<S> : never };
+/** Resource names preserved from a connector's resource tuple. */
+type ResourceName<Resources extends ReadonlyArray<ResourceDefinition>> = keyof ResourceRows<Resources> & string;
 /**
  * Takes a resource definition and returns the payload type accepted by
  * `to(resource, payload)`.
@@ -146,7 +160,7 @@ type WebhookRoute<Resources extends ReadonlyArray<ResourceDefinition> = Readonly
   readonly path: HttpRouter.PathInput;
   readonly ackMode: WebhookAckMode;
   readonly schema: Schema.Decoder<Payload$1>;
-  handler(context: WebhookRouteContext<Resources, Payload$1>): Effect.Effect<HttpServerResponse.HttpServerResponse, unknown>;
+  handler(context: WebhookRouteContext<Resources, Payload$1>): Effect.Effect<HttpServerResponse.HttpServerResponse, ConnectorError>;
 };
 type WebhookRouteInput<Resources extends ReadonlyArray<ResourceDefinition>, Payload$1> = WebhookRoute<Resources, Payload$1>;
 type ConnectorDefinition<Resources extends ReadonlyArray<ResourceDefinition> = ReadonlyArray<ResourceDefinition>> = {
@@ -156,5 +170,5 @@ type ConnectorDefinition<Resources extends ReadonlyArray<ResourceDefinition> = R
   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
+export { WebhookRouteInput as C, WebhookRouteContext as S, ResourceState as _, FetchChangesResult as a, WebhookHandler as b, ResourceBatch as c, ResourceMutation as d, ResourceName as f, ResourceSchema as g, ResourceRows as h, DeleteValue as i, ResourceDefinition as l, ResourceRow as m, ConnectorDefinition as n, FetchPageResult as o, ResourcePayload as p, Cursor as r, PageFetch as s, ChangesFetch as t, ResourceField as u, SyncState as v, WebhookRoute as x, WebhookAckMode as y };
+//# sourceMappingURL=types-B35J5YPu.d.ts.map

package/dist/webhook/index.d.ts

@@ -1,5 +1,6 @@
-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";
+import "../index-D54ySAKn.js";
+import { C as WebhookRouteInput, S as WebhookRouteContext, x as WebhookRoute, y as WebhookAckMode } from "../types-B35J5YPu.js";
+import "../service-IE5qaf9x.js";
+import "../index-Byr0Lf0C.js";
+import { n as route, r as router } from "../index-DKWIh6M1.js";
 export { WebhookAckMode, WebhookRoute, WebhookRouteContext, WebhookRouteInput, route, router };

package/dist/webhook/index.js

@@ -1,6 +1,8 @@
 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";
+import "../metrics-CWPy2Aqc.js";
+import "../constants-BRhIX_rz.js";
+import "../service-DuFiQwid.js";
+import { n as router } from "../server-CXTQ7odl.js";
+import { t as route } from "../webhook-DI-Afxkg.js";
 
 export { route, router };

package/dist/{webhook-BSA-tXtU.js → webhook-DI-Afxkg.js}

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

package/dist/{webhook-BSA-tXtU.js.map → webhook-DI-Afxkg.js.map}

@@ -1 +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"}
+{"version":3,"file":"webhook-DI-Afxkg.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"}