@useairfoil/connector-kit 0.5.0 → 0.5.1

package/dist/{index-DK9YcR6W.d.ts → index-Byr0Lf0C.d.ts}

@@ -1,6 +1,6 @@
-import { t as ConnectorError } from "./index-DyuT2jzP.js";
-import { c as ResourceBatch, n as ConnectorDefinition } from "./types-ZNrA-Dn0.js";
-import { a as PublisherService, i as Publisher, n as PublishOptions, r as PublishSource, t as PublishAck } from "./service-B7g_lHMI.js";
+import { t as ConnectorError } from "./index-D54ySAKn.js";
+import { c as ResourceBatch, n as ConnectorDefinition } from "./types-B35J5YPu.js";
+import { a as PublisherService, i as Publisher, n as PublishOptions, r as PublishSource, t as PublishAck } from "./service-IE5qaf9x.js";
 import { Layer } from "effect";
 import * as Wings from "@useairfoil/wings";
 
@@ -22,4 +22,4 @@ declare namespace index_d_exports {
 }
 //#endregion
 export { layerWings as i, layerConsole as n, WingsPublisherConfig as r, index_d_exports as t };
-//# sourceMappingURL=index-DK9YcR6W.d.ts.map
+//# sourceMappingURL=index-Byr0Lf0C.d.ts.map

package/dist/index-CBT-JX-T.d.ts

@@ -0,0 +1,173 @@
+import { Config, Option, Redacted, Schema, Types } from "effect";
+import * as effect_Effect0 from "effect/Effect";
+
+//#region src/manifest/number-schema.d.ts
+type NumberConstraints = {
+  readonly integer?: boolean;
+  readonly minimum?: number;
+};
+//#endregion
+//#region src/manifest/config.d.ts
+type ConfigFieldSpecBase = {
+  readonly runtimeKey: string;
+  readonly required: boolean;
+  readonly description?: string;
+};
+type ConfigFieldDefinition = ConfigFieldSpecBase & ({
+  readonly type: "string";
+  readonly secret: false;
+  readonly default?: string;
+  readonly values?: never;
+} | {
+  readonly type: "string";
+  readonly secret: true;
+  readonly default?: never;
+  readonly values?: never;
+} | {
+  readonly type: "number";
+  readonly secret: false;
+  readonly default?: number;
+  readonly values?: never;
+  readonly integer?: boolean;
+  readonly minimum?: number;
+} | {
+  readonly type: "boolean";
+  readonly secret: false;
+  readonly default?: boolean;
+  readonly values?: never;
+} | {
+  readonly type: "select";
+  readonly secret: false;
+  readonly default?: string;
+  readonly values: readonly [string, ...Array<string>];
+});
+/** Serializable, browser-safe metadata for one user-provided connector setting. */
+type ConfigFieldSpec = ConfigFieldDefinition & {
+  readonly name: string;
+};
+/** Pairs an Effect runtime config with the metadata used to generate its form field. */
+type ConfigField<A$1> = {
+  readonly config: Config.Config<A$1>;
+  readonly spec: ConfigFieldDefinition;
+};
+type FieldBaseOptions = {
+  readonly runtimeKey: string;
+  readonly description?: string;
+};
+type FieldOptions<A$1 extends string | number | boolean = string | number | boolean> = FieldBaseOptions & ({
+  readonly required?: true;
+  readonly default?: A$1;
+} | {
+  readonly required: false;
+  readonly default: A$1;
+});
+type NumberFieldOptions = FieldOptions<number> & NumberConstraints;
+type FieldsRecord = Record<string, ConfigField<unknown>>;
+type ConfigOf<Fields$1 extends FieldsRecord> = { readonly [Key in keyof Fields$1]: Fields$1[Key] extends ConfigField<infer A> ? A : never };
+/** Effect config and serializable manifest metadata produced from one field definition. */
+type ConnectorConfigDef<Fields$1 extends FieldsRecord> = {
+  readonly fields: { readonly [Key in keyof Fields$1]: Fields$1[Key] extends ConfigField<infer A> ? Config.Config<A> : never };
+  readonly config: Config.Config<ConfigOf<Fields$1>>;
+  readonly spec: ReadonlyArray<ConfigFieldSpec>;
+};
+type ConfigValuesOf<Def extends ConnectorConfigDef<FieldsRecord>> = Def extends ConnectorConfigDef<infer Fields> ? ConfigOf<Fields> : never;
+/** Defines a required non-empty string, optionally with a default. */
+declare const string: (options: FieldOptions<string>) => ConfigField<string>;
+/** Defines a finite number with optional integer, minimum, and default constraints. */
+declare const number: (options: NumberFieldOptions) => ConfigField<number>;
+/** Defines a boolean, optionally with a default. */
+declare const boolean: (options: FieldOptions<boolean>) => ConfigField<boolean>;
+/** Defines a string literal choice whose values are preserved in the inferred type. */
+declare const select: <const Values extends readonly [string, ...Array<string>]>(options: FieldOptions<Values[number]> & {
+  readonly values: Values;
+}) => ConfigField<Values[number]>;
+/** Defines a required, non-empty secret decoded as `Redacted<string>`. */
+declare const secret: (options: FieldBaseOptions & {
+  readonly required?: true;
+}) => ConfigField<Redacted.Redacted<string>>;
+/** Makes an existing field optional and represents a missing value as `Option.none()`. */
+declare const optional: <A$1>(field: ConfigField<A$1>) => ConfigField<Option.Option<A$1>>;
+/**
+ * Defines user-facing connector config once for both Effect runtime loading and
+ * frontend form generation. The object keys become logical form/API field names;
+ * `runtimeKey` remains the key read by Effect Config.
+ *
+ * @example
+ * ```ts
+ * const config = define({
+ *   apiUrl: string({ runtimeKey: "API_URL" }),
+ *   token: secret({ runtimeKey: "API_TOKEN" }),
+ * });
+ *
+ * const RuntimeConfig = config.config;
+ * const formFields = config.spec;
+ * ```
+ */
+declare const define: <const Fields$1 extends FieldsRecord>(fields: Fields$1) => ConnectorConfigDef<Fields$1>;
+//#endregion
+//#region src/manifest/manifest.d.ts
+type ResourceCapability = "backfill" | "changes" | "webhook";
+/** Browser-safe connector metadata consumed by the platform and runtime adapters. */
+type ConnectorManifest = {
+  readonly name: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly config: ReadonlyArray<ConfigFieldSpec>;
+  readonly resources: ReadonlyArray<{
+    readonly name: string;
+    readonly capabilities: ReadonlyArray<ResourceCapability>;
+  }>;
+};
+/**
+ * Defines browser-safe connector metadata while preserving literal names and capabilities.
+ *
+ * @example
+ * ```ts
+ * const manifest = define({
+ *   name: "producer-example",
+ *   title: "Example",
+ *   config: ExampleConfig.spec,
+ *   resources: [{ name: "orders", capabilities: ["backfill"] }],
+ * });
+ * ```
+ */
+declare const define$1: <const Manifest extends ConnectorManifest>(manifest: Manifest) => Manifest;
+//#endregion
+//#region src/manifest/schema.d.ts
+type FieldValueOf<Field$1 extends ConfigFieldSpec> = Field$1["type"] extends "number" ? number : Field$1["type"] extends "boolean" ? boolean : Field$1["values"] extends ReadonlyArray<string> ? Field$1["values"][number] : string;
+type ConnectorConfigValues<Manifest extends ConnectorManifest> = Types.Simplify<{ readonly [Field in Manifest["config"][number] as Field["required"] extends true ? Field["name"] : never]: FieldValueOf<Field> } & { readonly [Field in Manifest["config"][number] as Field["required"] extends true ? never : Field["name"]]?: FieldValueOf<Field> | undefined }> & object;
+type ConnectorConfigSchema<Manifest extends ConnectorManifest> = Schema.Codec<ConnectorConfigValues<Manifest>, unknown>;
+/** Flat primitive document keyed by the runtime keys consumed by Effect Config. */
+type RuntimeConfigDocument = Readonly<Record<string, string | number | boolean>>;
+/**
+ * Builds an Effect Schema for logical form/API values from a connector manifest.
+ *
+ * @example
+ * ```ts
+ * const decode = Schema.decodeUnknownEffect(configSchema(manifest));
+ * const values = decode({
+ *   apiUrl: "https://example.com",
+ *   retries: "3",
+ * });
+ * ```
+ */
+declare const configSchema: <const Manifest extends ConnectorManifest>(manifest: Manifest) => ConnectorConfigSchema<Manifest>;
+/** Decodes browser/API config, applies manifest defaults, and rejects undeclared fields. */
+declare const decodeConfig: <const Manifest extends ConnectorManifest>(manifest: Manifest, input: unknown) => effect_Effect0.Effect<ConnectorConfigValues<Manifest>, Schema.SchemaError, never>;
+/**
+ * Maps validated logical values to the flat runtime-key document mounted in a pod.
+ * Missing optional values are omitted.
+ *
+ * @example
+ * ```ts
+ * toRuntimeDocument(manifest, { apiUrl: "https://example.com" });
+ * // { API_URL: "https://example.com" }
+ * ```
+ */
+declare const toRuntimeDocument: <const Manifest extends ConnectorManifest>(manifest: Manifest, values: ConnectorConfigValues<Manifest>) => RuntimeConfigDocument;
+declare namespace index_d_exports {
+  export { ConfigField, ConfigFieldSpec, ConfigValuesOf, ConnectorConfigDef, ConnectorConfigSchema, ConnectorConfigValues, ConnectorManifest, ResourceCapability, RuntimeConfigDocument, boolean, configSchema, decodeConfig, define$1 as define, define as defineConfig, number, optional, secret, select, string, toRuntimeDocument };
+}
+//#endregion
+export { number as _, configSchema as a, select as b, ConnectorManifest as c, ConfigField as d, ConfigFieldSpec as f, define as g, boolean as h, RuntimeConfigDocument as i, ResourceCapability as l, ConnectorConfigDef as m, ConnectorConfigSchema as n, decodeConfig as o, ConfigValuesOf as p, ConnectorConfigValues as r, toRuntimeDocument as s, index_d_exports as t, define$1 as u, optional as v, string as x, secret as y };
+//# sourceMappingURL=index-CBT-JX-T.d.ts.map

package/dist/index-CTHVudvQ.d.ts

@@ -0,0 +1,41 @@
+import { Duration, Effect, Redacted } from "effect";
+
+//#region src/auth/token-cache.d.ts
+interface ExpiringToken {
+  /** The credential kept in memory by the cache. */
+  readonly value: Redacted.Redacted<string>;
+  /** The lifetime reported by the provider. */
+  readonly expiresIn: Duration.Duration;
+}
+interface TokenCache<E> {
+  /** Returns the cached token or performs one shared acquisition. */
+  readonly get: Effect.Effect<Redacted.Redacted<string>, E>;
+  /** Removes the cached token so the next `get` reacquires it. */
+  readonly invalidate: Effect.Effect<void>;
+}
+/**
+ * Creates a lazy, in-memory token cache around an acquisition effect.
+ *
+ * `refreshFactor` controls how much of the provider lifetime is cached. It is
+ * clamped between `0` and `1`.
+ *
+ * @example
+ * ```ts
+ * const cache = yield* makeTokenCache({
+ *   acquire: exchangeCredentials,
+ *   refreshFactor: 0.5,
+ * })
+ *
+ * const token = yield* cache.get
+ * ```
+ */
+declare const makeTokenCache: <E, R>(options: {
+  readonly acquire: Effect.Effect<ExpiringToken, E, R>;
+  readonly refreshFactor?: number;
+}) => Effect.Effect<TokenCache<E>, never, R>;
+declare namespace index_d_exports {
+  export { ExpiringToken, TokenCache, makeTokenCache };
+}
+//#endregion
+export { makeTokenCache as i, ExpiringToken as n, TokenCache as r, index_d_exports as t };
+//# sourceMappingURL=index-CTHVudvQ.d.ts.map

package/dist/index-CTLYQ74P.d.ts

@@ -0,0 +1,80 @@
+import { n as ConnectorDefinition } from "./types-B35J5YPu.js";
+import { i as StateStore } from "./index-Coh_SkBs.js";
+import { Schema } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import * as effect_Layer1 from "effect/Layer";
+
+//#region src/status/route.d.ts
+declare const statusRoute: (connector: ConnectorDefinition, path?: HttpRouter.PathInput) => effect_Layer1.Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Requires", StateStore>>;
+//#endregion
+//#region src/status/types.d.ts
+declare const SyncStateSchema: Schema.Literals<readonly ["pending", "backfilling", "live", "error"]>;
+type SyncState = Schema.Schema.Type<typeof SyncStateSchema>;
+/** Safe source failure returned by the status endpoint. */
+declare const ResourceErrorSchema: Schema.Struct<{
+  readonly at: Schema.String;
+  readonly source: Schema.Literals<readonly ["backfill", "changes"]>;
+  readonly operation: Schema.Literals<readonly ["fetch", "publish", "checkpoint"]>;
+  readonly code: Schema.Literals<readonly ["fetch_failed", "publish_failed", "checkpoint_failed"]>;
+  readonly message: Schema.String;
+}>;
+type ResourceError = Schema.Schema.Type<typeof ResourceErrorSchema>;
+declare const ResourceStatusSchema: Schema.Struct<{
+  readonly backfill: Schema.optional<Schema.Struct<{
+    readonly cutoff: Schema.Union<readonly [Schema.String, Schema.Number]>;
+    readonly pageCursor: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Number]>>;
+    readonly completed: Schema.Boolean;
+    readonly lastSuccessAt: Schema.optional<Schema.String>;
+  }>>;
+  readonly changes: Schema.optional<Schema.Struct<{
+    readonly cursor: Schema.Union<readonly [Schema.String, Schema.Number]>;
+    readonly lastSuccessAt: Schema.optional<Schema.String>;
+  }>>;
+  readonly lastError: Schema.optional<Schema.Struct<{
+    readonly at: Schema.String;
+    readonly source: Schema.Literals<readonly ["backfill", "changes"]>;
+    readonly operation: Schema.Literals<readonly ["fetch", "publish", "checkpoint"]>;
+    readonly code: Schema.Literals<readonly ["fetch_failed", "publish_failed", "checkpoint_failed"]>;
+    readonly message: Schema.String;
+  }>>;
+  readonly name: Schema.String;
+  readonly state: Schema.Literals<readonly ["pending", "backfilling", "live", "error"]>;
+}>;
+type ResourceStatus = Schema.Schema.Type<typeof ResourceStatusSchema>;
+declare const StatusResponseSchema: Schema.Struct<{
+  readonly connector: Schema.String;
+  readonly resources: Schema.$Array<Schema.Struct<{
+    readonly backfill: Schema.optional<Schema.Struct<{
+      readonly cutoff: Schema.Union<readonly [Schema.String, Schema.Number]>;
+      readonly pageCursor: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Number]>>;
+      readonly completed: Schema.Boolean;
+      readonly lastSuccessAt: Schema.optional<Schema.String>;
+    }>>;
+    readonly changes: Schema.optional<Schema.Struct<{
+      readonly cursor: Schema.Union<readonly [Schema.String, Schema.Number]>;
+      readonly lastSuccessAt: Schema.optional<Schema.String>;
+    }>>;
+    readonly lastError: Schema.optional<Schema.Struct<{
+      readonly at: Schema.String;
+      readonly source: Schema.Literals<readonly ["backfill", "changes"]>;
+      readonly operation: Schema.Literals<readonly ["fetch", "publish", "checkpoint"]>;
+      readonly code: Schema.Literals<readonly ["fetch_failed", "publish_failed", "checkpoint_failed"]>;
+      readonly message: Schema.String;
+    }>>;
+    readonly name: Schema.String;
+    readonly state: Schema.Literals<readonly ["pending", "backfilling", "live", "error"]>;
+  }>>;
+}>;
+type StatusResponse = Schema.Schema.Type<typeof StatusResponseSchema>;
+/** Returned when durable resource status cannot be read. */
+declare const StatusUnavailableResponseSchema: Schema.Struct<{
+  readonly ok: Schema.Literal<false>;
+  readonly error: Schema.String;
+}>;
+type StatusUnavailableResponse = Schema.Schema.Type<typeof StatusUnavailableResponseSchema>;
+declare namespace index_d_exports {
+  export { ResourceError, ResourceErrorSchema, ResourceStatus, ResourceStatusSchema, StatusResponse, StatusResponseSchema, StatusUnavailableResponse, StatusUnavailableResponseSchema, SyncState, SyncStateSchema, statusRoute };
+}
+//#endregion
+export { ResourceStatusSchema as a, StatusUnavailableResponse as c, SyncStateSchema as d, statusRoute as f, ResourceStatus as i, StatusUnavailableResponseSchema as l, ResourceError as n, StatusResponse as o, ResourceErrorSchema as r, StatusResponseSchema as s, index_d_exports as t, SyncState as u };
+//# sourceMappingURL=index-CTLYQ74P.d.ts.map

package/dist/index-Coh_SkBs.d.ts

@@ -0,0 +1,95 @@
+import { t as ConnectorError } from "./index-D54ySAKn.js";
+import { Config, Context, Effect, Layer, Schema } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+
+//#region src/state-store/schema.d.ts
+/** Durable progress for a finite historical backfill. */
+declare const BackfillStateSchema: Schema.Struct<{
+  readonly cutoff: Schema.Union<readonly [Schema.String, Schema.Number]>;
+  readonly pageCursor: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Number]>>;
+  readonly completed: Schema.Boolean;
+  readonly lastSuccessAt: Schema.optional<Schema.String>;
+}>;
+/** Durable cursor for an ongoing incremental changes stream. */
+declare const ChangesStateSchema: Schema.Struct<{
+  readonly cursor: Schema.Union<readonly [Schema.String, Schema.Number]>;
+  readonly lastSuccessAt: Schema.optional<Schema.String>;
+}>;
+declare const StateSourceSchema: Schema.Literals<readonly ["backfill", "changes"]>;
+declare const StateOperationSchema: Schema.Literals<readonly ["fetch", "publish", "checkpoint"]>;
+/** Complete persisted state assembled from independently stored components. */
+declare const ResourceStateSchema: Schema.Struct<{
+  readonly backfill: Schema.optional<Schema.Struct<{
+    readonly cutoff: Schema.Union<readonly [Schema.String, Schema.Number]>;
+    readonly pageCursor: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Number]>>;
+    readonly completed: Schema.Boolean;
+    readonly lastSuccessAt: Schema.optional<Schema.String>;
+  }>>;
+  readonly changes: Schema.optional<Schema.Struct<{
+    readonly cursor: Schema.Union<readonly [Schema.String, Schema.Number]>;
+    readonly lastSuccessAt: Schema.optional<Schema.String>;
+  }>>;
+  readonly lastError: Schema.optional<Schema.Struct<{
+    readonly at: Schema.String;
+    readonly source: Schema.Literals<readonly ["backfill", "changes"]>;
+    readonly operation: Schema.Literals<readonly ["fetch", "publish", "checkpoint"]>;
+    readonly code: Schema.Literals<readonly ["fetch_failed", "publish_failed", "checkpoint_failed"]>;
+    readonly message: Schema.String;
+  }>>;
+}>;
+type PersistedBackfillState = Schema.Schema.Type<typeof BackfillStateSchema>;
+type PersistedChangesState = Schema.Schema.Type<typeof ChangesStateSchema>;
+type StateSource = Schema.Schema.Type<typeof StateSourceSchema>;
+type StateOperation = Schema.Schema.Type<typeof StateOperationSchema>;
+type PersistedResourceState = Schema.Schema.Type<typeof ResourceStateSchema>;
+//#endregion
+//#region src/state-store/service.d.ts
+/** Connector-facing durable state operations, independent of the storage backend. */
+interface StateStoreService {
+  readonly getResourceState: (resource: string) => Effect.Effect<PersistedResourceState | undefined, ConnectorError>;
+  readonly setBackfillState: (resource: string, state: PersistedBackfillState) => Effect.Effect<void, ConnectorError>;
+  readonly setChangesState: (resource: string, state: PersistedChangesState) => Effect.Effect<void, ConnectorError>;
+  readonly setResourceError: (resource: string, source: StateSource, operation: StateOperation) => Effect.Effect<void, ConnectorError>;
+  readonly clearResourceError: (resource: string, source: StateSource) => Effect.Effect<void, ConnectorError>;
+}
+declare const StateStore_base: Context.ServiceClass<StateStore, "@useairfoil/connector-kit/StateStore", StateStoreService>;
+/**
+ * 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" });
+ * });
+ * ```
+ */
+declare class StateStore extends StateStore_base {}
+//#endregion
+//#region src/state-store/layer-memory.d.ts
+/** Process-local state for tests and explicit local sandbox commands. */
+declare const layerMemory: Layer.Layer<StateStore>;
+//#endregion
+//#region src/state-store/layer-sql.d.ts
+/**
+ * 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));
+ * ```
+ */
+declare const layerSql: () => Layer.Layer<StateStore, Config.ConfigError, SqlClient.SqlClient>;
+declare namespace index_d_exports {
+  export { StateStore, StateStoreService, layerMemory, layerSql };
+}
+//#endregion
+export { StateStoreService as a, StateStore as i, layerSql as n, layerMemory as r, index_d_exports as t };
+//# sourceMappingURL=index-Coh_SkBs.d.ts.map

package/dist/{index-DyuT2jzP.d.ts → index-D54ySAKn.d.ts}

@@ -11,4 +11,4 @@ declare class ConnectorError extends ConnectorError_base<{
 }> {}
 //#endregion
 export { ConnectorError as t };
-//# sourceMappingURL=index-DyuT2jzP.d.ts.map
+//# sourceMappingURL=index-D54ySAKn.d.ts.map

package/dist/{index-BlhJCpEk.d.ts → index-DtJX_tic.d.ts}

@@ -1,18 +1,39 @@
-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 { t as ConnectorError } from "./index-D54ySAKn.js";
+import { b as WebhookHandler, d as ResourceMutation, f as ResourceName, g as ResourceSchema, i as DeleteValue, l as ResourceDefinition, n as ConnectorDefinition, r as Cursor, s as PageFetch, t as ChangesFetch } from "./types-B35J5YPu.js";
+import { i as Publisher } from "./service-IE5qaf9x.js";
+import { i as StateStore } from "./index-Coh_SkBs.js";
+import { Config, Context, Duration, 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/connector-app/check.d.ts
+type ResourceCheckResult = {
+  readonly _tag: "ok";
+} | {
+  readonly _tag: "error";
+  readonly message: string;
+};
+type CheckOptions<Name extends string> = {
+  readonly resources: ReadonlyArray<Name>;
+};
+type ResourceCheckResults<Name extends PropertyKey> = { readonly [Key in Name]: ResourceCheckResult };
+type CheckResult<Resources extends ReadonlyArray<ResourceDefinition>, Name extends ResourceName<Resources> = ResourceName<Resources>> = ResourceCheckResults<Name>;
+type CheckFailure = {
+  readonly message: string;
+};
+/**
+ * Builds the connector service from its layer and validates only the selected
+ * resources. The layer remains open until every check finishes.
+ */
+declare function check<Identifier, const Resources extends ReadonlyArray<ResourceDefinition>, E extends CheckFailure, R, const Name extends ResourceName<Resources>>(service: Context.Key<Identifier, ConnectorDefinition<Resources>>, layer: Layer.Layer<Identifier, E, R>, options: CheckOptions<Name>): Effect.Effect<CheckResult<Resources, Name>, never, R>;
+//#endregion
 //#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>;
+  entity: <S extends ResourceSchema, Payload = never, R = never, const Name extends string = string>(definition: ResourceDefinition<S, Payload, R, Name>) => ResourceDefinition<S, Payload, R, Name>;
   webhook: <Payload, Row extends object = never>(definition: WebhookHandler<Row, Payload>) => WebhookHandler<Row, Payload>;
   upsert: <Row extends object>(row: Row) => ResourceMutation<Row>;
   delete: (options: {
@@ -31,7 +52,7 @@ declare const Cursor$1: {
   nowIsoDateTime: Effect.Effect<string, never, never>;
 };
 declare namespace telemetry_d_exports {
-  export { Attr, EventAttr, EventName, OtlpTracingConfig, OtlpTracingOptions, SpanName, addCurrentSpanEvent, annotateError, layer, layerConfig, layerOtlpTracing };
+  export { Attr, EventAttr, EventName, OtlpMetricsOptions, OtlpTracingConfig, OtlpTracingOptions, SpanName, addCurrentSpanEvent, annotateError, layer, layerConfig, layerMetricsConsoleDump, layerOtlp, layerOtlpMetrics, layerOtlpTracing };
 }
 /** Canonical span names emitted by connector-kit runtime instrumentation. */
 declare const SpanName: {
@@ -81,6 +102,9 @@ type OtlpTracingOptions = {
   /** Additional connector-specific header names or regexes to redact from HTTP logs/traces. */
   readonly redactedHeaders?: ReadonlyArray<string | RegExp>;
 };
+type OtlpMetricsOptions = {
+  readonly exportInterval?: Duration.Input;
+};
 /**
  * Trace-only OTLP export with sensitive HTTP header redaction.
  * Takes direct config values — no `ConfigProvider` required.
@@ -106,6 +130,9 @@ declare const layerConfig: (config: Config.Wrap<OtlpTracingConfig>, options?: Ot
  * `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>;
+declare const layerOtlpMetrics: (options?: OtlpMetricsOptions) => Layer.Layer<never, Error | Config.ConfigError, effect_unstable_http_HttpClient0.HttpClient>;
+declare const layerOtlp: (options?: OtlpTracingOptions & OtlpMetricsOptions) => Layer.Layer<never, Error | Config.ConfigError, effect_unstable_http_HttpClient0.HttpClient>;
+declare const layerMetricsConsoleDump: (interval?: Duration.Input) => Layer.Layer<never, never, never>;
 //#endregion
 //#region src/connector-app/start.d.ts
 type App = ConnectorDefinition;
@@ -113,12 +140,14 @@ type StartOptions = {
   readonly port: number;
   readonly initialCutoff?: Cursor.Value;
   readonly healthPath?: HttpRouter.PathInput;
+  readonly metricsPath?: HttpRouter.PathInput | false;
+  readonly statusPath?: HttpRouter.PathInput | false;
   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 };
+  export { App, CheckOptions, CheckResult, ResourceCheckResult, StartOptions, check, 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
+export { telemetry_d_exports as a, Fetch as c, CheckResult as d, ResourceCheckResult as f, start as i, Resource as l, App as n, Connector as o, check as p, StartOptions as r, Cursor$1 as s, index_d_exports as t, CheckOptions as u };
+//# sourceMappingURL=index-DtJX_tic.d.ts.map

package/dist/{index-8KnVpoZp.d.ts → index-J42AZaXU.d.ts}

@@ -1,7 +1,7 @@
-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 { t as ConnectorError } from "./index-D54ySAKn.js";
+import { l as ResourceDefinition, n as ConnectorDefinition, r as Cursor, x as WebhookRoute } from "./types-B35J5YPu.js";
+import { i as Publisher } from "./service-IE5qaf9x.js";
+import { i as StateStore } from "./index-Coh_SkBs.js";
 import { Effect } from "effect";
 import { HttpRouter, HttpServer } from "effect/unstable/http";
 
@@ -13,6 +13,8 @@ type RunOptions = RunBaseOptions & {
   readonly webhook?: {
     readonly routes: ReadonlyArray<WebhookRoute>;
     readonly healthPath?: HttpRouter.PathInput;
+    readonly metricsPath?: HttpRouter.PathInput | false;
+    readonly statusPath?: HttpRouter.PathInput | false;
     readonly disableHttpLogger?: boolean;
   };
 };
@@ -22,6 +24,10 @@ type RunNoWebhookOptions = RunBaseOptions & {
 type RunWebhookOptions = RunOptions & {
   readonly webhook: NonNullable<RunOptions["webhook"]>;
 };
+/**
+ * Runs all connector ingestion loops. Callers provide the Publisher and
+ * StateStore layers; webhook mode additionally requires an HttpServer layer.
+ */
 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 {
@@ -29,4 +35,4 @@ declare namespace index_d_exports {
 }
 //#endregion
 export { RunOptions as n, run as r, index_d_exports as t };
-//# sourceMappingURL=index-8KnVpoZp.d.ts.map
+//# sourceMappingURL=index-J42AZaXU.d.ts.map

package/dist/{index-CQJsFJs3.d.ts → index-fIIBVAai.d.ts}

@@ -1,5 +1,5 @@
-import { _ as WebhookAckMode, b as WebhookRouteContext, c as ResourceBatch, l as ResourceDefinition, x as WebhookRouteInput, y as WebhookRoute } from "./types-ZNrA-Dn0.js";
-import { i as Publisher } from "./service-B7g_lHMI.js";
+import { C as WebhookRouteInput, S as WebhookRouteContext, c as ResourceBatch, l as ResourceDefinition, x as WebhookRoute, y as WebhookAckMode } from "./types-B35J5YPu.js";
+import { i as Publisher } from "./service-IE5qaf9x.js";
 import { Context, Queue } from "effect";
 import { HttpRouter } from "effect/unstable/http";
 import * as effect_Layer0 from "effect/Layer";
@@ -13,11 +13,13 @@ declare const WebhookQueue_base: Context.ServiceClass<WebhookQueue, "@useairfoil
   readonly queue: Queue.Queue<QueuedWebhookBatch>;
 }>;
 declare class WebhookQueue extends WebhookQueue_base {}
-declare const router: (routes: ReadonlyArray<WebhookRoute>) => effect_Layer0.Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Requires", Publisher> | HttpRouter.Request<"Requires", WebhookQueue>>;
+declare const router: (routes: ReadonlyArray<WebhookRoute>, options: {
+  readonly connectorName: string;
+}) => effect_Layer0.Layer<never, never, HttpRouter.HttpRouter | HttpRouter.Request<"Requires", WebhookQueue> | HttpRouter.Request<"Requires", Publisher>>;
 declare namespace index_d_exports {
   export { WebhookAckMode, WebhookRoute, WebhookRouteContext, WebhookRouteInput, route, router };
 }
 declare const route: <const Resources extends ReadonlyArray<ResourceDefinition>, Payload>(definition: WebhookRouteInput<Resources, Payload>) => WebhookRoute<Resources, Payload>;
 //#endregion
 export { route as n, router as r, index_d_exports as t };
-//# sourceMappingURL=index-CQJsFJs3.d.ts.map
+//# sourceMappingURL=index-fIIBVAai.d.ts.map

package/dist/index-o1-Z3n7V.d.ts

@@ -0,0 +1,55 @@
+import { FileSystem } from "effect";
+import * as effect_Types0 from "effect/Types";
+import * as effect_Cause0 from "effect/Cause";
+import * as effect_Layer0 from "effect/Layer";
+
+//#region src/runtime-config/error.d.ts
+type RuntimeConfigErrorCode = "CONFIG_PATH_MISSING" | "CONFIG_FILE_UNREADABLE" | "CONFIG_JSON_INVALID";
+declare const RuntimeConfigError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => effect_Cause0.YieldableError & {
+  readonly _tag: "RuntimeConfigError";
+} & Readonly<A>;
+/** Expected hosted-config failure with a stable code and diagnostic cause. */
+declare class RuntimeConfigError extends RuntimeConfigError_base<{
+  readonly code: RuntimeConfigErrorCode;
+  readonly message: string;
+  readonly cause: Error;
+}> {}
+//#endregion
+//#region src/runtime-config/constants.d.ts
+/** Shared runtime keys owned by Airfoil rather than an individual connector. */
+declare const PlatformRuntimeKey: {
+  readonly configPath: "AIRFOIL_CONFIG_PATH";
+  readonly connectorInstanceId: "AIRFOIL_CONNECTOR_INSTANCE_ID";
+  readonly stateTable: "AIRFOIL_STATE_TABLE";
+  readonly postgresConnectionString: "POSTGRES_CONNECTION_STRING";
+  readonly wingsHost: "WINGS_HOST";
+  readonly wingsNamespace: "WINGS_NAMESPACE";
+  readonly otelEnabled: "OTEL_ENABLED";
+  readonly otelExporterOtlpEndpoint: "OTEL_EXPORTER_OTLP_ENDPOINT";
+  readonly otelExporterOtlpHeaders: "OTEL_EXPORTER_OTLP_HEADERS";
+  readonly otelServiceName: "OTEL_SERVICE_NAME";
+  readonly otelServiceVersion: "OTEL_SERVICE_VERSION";
+  readonly otelResourceAttributes: "OTEL_RESOURCE_ATTRIBUTES";
+};
+/** Defaults for optional platform-owned runtime configuration. */
+declare const PlatformRuntimeDefault: {
+  readonly stateTable: "_airfoil_connectors_state";
+};
+//#endregion
+//#region src/runtime-config/layer.d.ts
+/**
+ * Loads the required JSON file and lets environment values override it per key.
+ * Connector field validation remains in the connector's Effect Config.
+ *
+ * @example
+ * ```ts
+ * program.pipe(Effect.provide(layerHosted()));
+ * ```
+ */
+declare const layerHosted: () => effect_Layer0.Layer<never, RuntimeConfigError, FileSystem.FileSystem>;
+declare namespace index_d_exports {
+  export { PlatformRuntimeDefault, PlatformRuntimeKey, RuntimeConfigError, RuntimeConfigErrorCode, layerHosted };
+}
+//#endregion
+export { RuntimeConfigError as a, PlatformRuntimeKey as i, layerHosted as n, RuntimeConfigErrorCode as o, PlatformRuntimeDefault as r, index_d_exports as t };
+//# sourceMappingURL=index-o1-Z3n7V.d.ts.map