@useairfoil/connector-kit 0.5.3 → 0.6.0

package/dist/table-bindings-Dp1DhTeS.js

@@ -0,0 +1,106 @@
+import { n as PlatformRuntimeKey } from "./constants-D113Ut1x.js";
+import { Config, Data, Effect, Schema } from "effect";
+import * as Wings from "@useairfoil/wings";
+
+//#region src/runtime-config/error.ts
+/** Expected hosted-config failure with a stable code and diagnostic cause. */
+var RuntimeConfigError = class extends Data.TaggedError("RuntimeConfigError") {};
+
+//#endregion
+//#region src/runtime-config/table-bindings.ts
+const RawBindingsSchema = Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown));
+const duplicateTopLevelKey = (json) => {
+	const keys = /* @__PURE__ */ new Set();
+	let depth = 0;
+	let expectKey = false;
+	for (let index = 0; index < json.length; index += 1) {
+		const char = json[index];
+		if (char === "\"") {
+			const start = index;
+			for (index += 1; index < json.length; index += 1) if (json[index] === "\\") index += 1;
+			else if (json[index] === "\"") break;
+			if (depth === 1 && expectKey) {
+				const key = JSON.parse(json.slice(start, index + 1));
+				if (keys.has(key)) return key;
+				keys.add(key);
+				expectKey = false;
+			}
+			continue;
+		}
+		if (char === "{") {
+			depth += 1;
+			if (depth === 1) expectKey = true;
+		} else if (char === "}") depth -= 1;
+		else if (char === "," && depth === 1) expectKey = true;
+	}
+};
+const asError = (cause) => cause instanceof Error ? cause : new Error(String(cause));
+const fail = (code, message) => new RuntimeConfigError({
+	code,
+	message,
+	cause: new Error(message)
+});
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const hasExactKeys = (value, allowed) => {
+	const keys = Object.keys(value);
+	return keys.length === allowed.filter((key) => key in value).length && keys.every((key) => allowed.includes(key));
+};
+const nonEmptyName = (value) => {
+	if (typeof value !== "string" || value.length === 0 || value.trim() !== value) throw fail("TABLE_BINDINGS_INVALID", "Table binding names must be non-empty strings");
+	return value;
+};
+const resolveBinding = (input) => Effect.gen(function* () {
+	const binding = yield* Effect.try({
+		try: () => {
+			if (typeof input === "string") return { name: nonEmptyName(input) };
+			if (!isRecord(input) || !hasExactKeys(input, ["name", "partition"])) throw fail("TABLE_BINDINGS_INVALID", "Table bindings must be a name string or an object containing name and optional partition");
+			return {
+				name: nonEmptyName(input.name),
+				partition: input.partition
+			};
+		},
+		catch: (cause) => cause instanceof RuntimeConfigError ? cause : fail("TABLE_BINDINGS_INVALID", "Hosted table binding is invalid")
+	});
+	if (!("partition" in binding) || binding.partition === void 0) return { name: binding.name };
+	const partitionValue = yield* Wings.PartitionValue.decodeJson(binding.partition).pipe(Effect.mapError((cause) => new RuntimeConfigError({
+		code: "TABLE_BINDINGS_INVALID",
+		message: "Hosted table binding has an invalid partition value",
+		cause
+	})));
+	return {
+		name: binding.name,
+		partitionValue
+	};
+});
+/** Loads and validates the complete hosted Wings table map for a connector. */
+const loadTableBindings = (connector) => Effect.gen(function* () {
+	const raw = yield* Config.nonEmptyString(PlatformRuntimeKey.tableBindings).pipe(Effect.mapError((cause) => new RuntimeConfigError({
+		code: "TABLE_BINDINGS_MISSING",
+		message: `${PlatformRuntimeKey.tableBindings} is required in hosted mode`,
+		cause: asError(cause)
+	})));
+	if ((yield* Effect.try({
+		try: () => duplicateTopLevelKey(raw),
+		catch: (cause) => new RuntimeConfigError({
+			code: "TABLE_BINDINGS_INVALID",
+			message: "Hosted table bindings are not valid JSON",
+			cause: asError(cause)
+		})
+	})) !== void 0) return yield* Effect.fail(fail("TABLE_BINDINGS_INVALID", "Hosted table bindings contain a duplicate resource"));
+	const decoded = yield* Schema.decodeUnknownEffect(RawBindingsSchema)(raw).pipe(Effect.mapError((cause) => new RuntimeConfigError({
+		code: "TABLE_BINDINGS_INVALID",
+		message: "Hosted table bindings are not valid JSON",
+		cause: asError(cause)
+	})));
+	const expected = new Set(connector.resources.map((resource) => resource.name));
+	const actual = Object.keys(decoded);
+	const missing = [...expected].filter((name) => !(name in decoded));
+	const unknown = actual.filter((name) => !expected.has(name));
+	if (missing.length > 0 || unknown.length > 0) return yield* Effect.fail(fail("TABLE_BINDINGS_MISMATCH", `Hosted table bindings do not match connector resources (missing: ${missing.join(", ") || "none"}; unknown resources: ${unknown.length})`));
+	const entries = yield* Effect.forEach(actual, (name) => resolveBinding(decoded[name]).pipe(Effect.map((binding) => [name, binding])));
+	return Object.fromEntries(entries);
+});
+
+//#endregion
+export { RuntimeConfigError as n, loadTableBindings as t };
+//# sourceMappingURL=table-bindings-Dp1DhTeS.js.map

package/dist/table-bindings-Dp1DhTeS.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-bindings-Dp1DhTeS.js","names":[],"sources":["../src/runtime-config/error.ts","../src/runtime-config/table-bindings.ts"],"sourcesContent":["import { Data } from \"effect\";\n\nexport type RuntimeConfigErrorCode =\n  | \"CONFIG_PATH_MISSING\"\n  | \"CONFIG_FILE_UNREADABLE\"\n  | \"CONFIG_JSON_INVALID\"\n  | \"TABLE_BINDINGS_MISSING\"\n  | \"TABLE_BINDINGS_INVALID\"\n  | \"TABLE_BINDINGS_MISMATCH\";\n\n/** Expected hosted-config failure with a stable code and diagnostic cause. */\nexport class RuntimeConfigError extends Data.TaggedError(\"RuntimeConfigError\")<{\n  readonly code: RuntimeConfigErrorCode;\n  readonly message: string;\n  readonly cause: Error;\n}> {}\n","import * as Wings from \"@useairfoil/wings\";\nimport { Config, Effect, Schema } from \"effect\";\n\nimport type { ConnectorDefinition, ResourceName } from \"../core/types\";\n\nimport { PlatformRuntimeKey } from \"./constants\";\nimport { RuntimeConfigError } from \"./error\";\n\n/** Table binding shape accepted in `AIRFOIL_TABLE_BINDINGS`. */\nexport type HostedTableBinding =\n  | string\n  | {\n      readonly name: string;\n      readonly partition?: Wings.PartitionValue.Json;\n    };\n\n/** Validated table binding ready for the Wings publisher. */\nexport type ResolvedTableBinding = {\n  readonly name: string;\n  readonly partitionValue?: Wings.PartitionValue.PartitionValue;\n};\n\n/** One resolved binding for each resource in a connector manifest. */\nexport type ResolvedTableBindings<Connector extends ConnectorDefinition> = Readonly<\n  Record<ResourceName<Connector[\"resources\"]>, ResolvedTableBinding>\n>;\n\nconst RawBindingsSchema = Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown));\n\n// JSON.parse keeps the last duplicate key, so check before decoding.\nconst duplicateTopLevelKey = (json: string): string | undefined => {\n  const keys = new Set<string>();\n  let depth = 0;\n  let expectKey = false;\n  for (let index = 0; index < json.length; index += 1) {\n    const char = json[index];\n    if (char === '\"') {\n      const start = index;\n      for (index += 1; index < json.length; index += 1) {\n        if (json[index] === \"\\\\\") {\n          index += 1;\n        } else if (json[index] === '\"') {\n          break;\n        }\n      }\n      if (depth === 1 && expectKey) {\n        const key = JSON.parse(json.slice(start, index + 1)) as string;\n        if (keys.has(key)) return key;\n        keys.add(key);\n        expectKey = false;\n      }\n      continue;\n    }\n    if (char === \"{\") {\n      depth += 1;\n      if (depth === 1) expectKey = true;\n    } else if (char === \"}\") {\n      depth -= 1;\n    } else if (char === \",\" && depth === 1) {\n      expectKey = true;\n    }\n  }\n  return undefined;\n};\n\nconst asError = (cause: unknown): Error =>\n  cause instanceof Error ? cause : new Error(String(cause));\n\nconst fail = (code: \"TABLE_BINDINGS_INVALID\" | \"TABLE_BINDINGS_MISMATCH\", message: string) =>\n  new RuntimeConfigError({ code, message, cause: new Error(message) });\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\nconst hasExactKeys = (value: Record<string, unknown>, allowed: ReadonlyArray<string>) => {\n  const keys = Object.keys(value);\n  return (\n    keys.length === allowed.filter((key) => key in value).length &&\n    keys.every((key) => allowed.includes(key))\n  );\n};\n\nconst nonEmptyName = (value: unknown): string => {\n  if (typeof value !== \"string\" || value.length === 0 || value.trim() !== value) {\n    throw fail(\"TABLE_BINDINGS_INVALID\", \"Table binding names must be non-empty strings\");\n  }\n  return value;\n};\n\nconst resolveBinding = (input: unknown): Effect.Effect<ResolvedTableBinding, RuntimeConfigError> =>\n  Effect.gen(function* () {\n    const binding = yield* Effect.try({\n      try: () => {\n        if (typeof input === \"string\") return { name: nonEmptyName(input) } as const;\n        if (!isRecord(input) || !hasExactKeys(input, [\"name\", \"partition\"])) {\n          throw fail(\n            \"TABLE_BINDINGS_INVALID\",\n            \"Table bindings must be a name string or an object containing name and optional partition\",\n          );\n        }\n        return { name: nonEmptyName(input.name), partition: input.partition } as const;\n      },\n      catch: (cause) =>\n        cause instanceof RuntimeConfigError\n          ? cause\n          : fail(\"TABLE_BINDINGS_INVALID\", \"Hosted table binding is invalid\"),\n    });\n    if (!(\"partition\" in binding) || binding.partition === undefined) {\n      return { name: binding.name };\n    }\n    const partitionValue = yield* Wings.PartitionValue.decodeJson(binding.partition).pipe(\n      Effect.mapError(\n        (cause) =>\n          new RuntimeConfigError({\n            code: \"TABLE_BINDINGS_INVALID\",\n            message: \"Hosted table binding has an invalid partition value\",\n            cause,\n          }),\n      ),\n    );\n    return { name: binding.name, partitionValue };\n  });\n\n/** Loads and validates the complete hosted Wings table map for a connector. */\nexport const loadTableBindings = <const Connector extends ConnectorDefinition>(\n  connector: Connector,\n): Effect.Effect<ResolvedTableBindings<Connector>, RuntimeConfigError> =>\n  Effect.gen(function* () {\n    const raw = yield* Config.nonEmptyString(PlatformRuntimeKey.tableBindings).pipe(\n      Effect.mapError(\n        (cause) =>\n          new RuntimeConfigError({\n            code: \"TABLE_BINDINGS_MISSING\",\n            message: `${PlatformRuntimeKey.tableBindings} is required in hosted mode`,\n            cause: asError(cause),\n          }),\n      ),\n    );\n    const duplicate = yield* Effect.try({\n      try: () => duplicateTopLevelKey(raw),\n      catch: (cause) =>\n        new RuntimeConfigError({\n          code: \"TABLE_BINDINGS_INVALID\",\n          message: \"Hosted table bindings are not valid JSON\",\n          cause: asError(cause),\n        }),\n    });\n    if (duplicate !== undefined) {\n      return yield* Effect.fail(\n        fail(\"TABLE_BINDINGS_INVALID\", \"Hosted table bindings contain a duplicate resource\"),\n      );\n    }\n    const decoded = yield* Schema.decodeUnknownEffect(RawBindingsSchema)(raw).pipe(\n      Effect.mapError(\n        (cause) =>\n          new RuntimeConfigError({\n            code: \"TABLE_BINDINGS_INVALID\",\n            message: \"Hosted table bindings are not valid JSON\",\n            cause: asError(cause),\n          }),\n      ),\n    );\n    // Starting with a partial map would leave some manifest resources unwired.\n    const expected = new Set(connector.resources.map((resource) => resource.name));\n    const actual = Object.keys(decoded);\n    const missing = [...expected].filter((name) => !(name in decoded));\n    const unknown = actual.filter((name) => !expected.has(name));\n    if (missing.length > 0 || unknown.length > 0) {\n      return yield* Effect.fail(\n        fail(\n          \"TABLE_BINDINGS_MISMATCH\",\n          `Hosted table bindings do not match connector resources (missing: ${missing.join(\", \") || \"none\"}; unknown resources: ${unknown.length})`,\n        ),\n      );\n    }\n    const entries = yield* Effect.forEach(actual, (name) =>\n      resolveBinding(decoded[name]).pipe(Effect.map((binding) => [name, binding] as const)),\n    );\n    return Object.fromEntries(entries) as ResolvedTableBindings<Connector>;\n  });\n"],"mappings":";;;;;;AAWA,IAAa,qBAAb,cAAwC,KAAK,YAAY,qBAAqB,CAI3E;;;;ACYH,MAAM,oBAAoB,OAAO,eAAe,OAAO,OAAO,OAAO,QAAQ,OAAO,QAAQ,CAAC;AAG7F,MAAM,wBAAwB,SAAqC;CACjE,MAAM,uBAAO,IAAI,KAAa;CAC9B,IAAI,QAAQ;CACZ,IAAI,YAAY;AAChB,MAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,QAAQ,SAAS,GAAG;EACnD,MAAM,OAAO,KAAK;AAClB,MAAI,SAAS,MAAK;GAChB,MAAM,QAAQ;AACd,QAAK,SAAS,GAAG,QAAQ,KAAK,QAAQ,SAAS,EAC7C,KAAI,KAAK,WAAW,KAClB,UAAS;YACA,KAAK,WAAW,KACzB;AAGJ,OAAI,UAAU,KAAK,WAAW;IAC5B,MAAM,MAAM,KAAK,MAAM,KAAK,MAAM,OAAO,QAAQ,EAAE,CAAC;AACpD,QAAI,KAAK,IAAI,IAAI,CAAE,QAAO;AAC1B,SAAK,IAAI,IAAI;AACb,gBAAY;;AAEd;;AAEF,MAAI,SAAS,KAAK;AAChB,YAAS;AACT,OAAI,UAAU,EAAG,aAAY;aACpB,SAAS,IAClB,UAAS;WACA,SAAS,OAAO,UAAU,EACnC,aAAY;;;AAMlB,MAAM,WAAW,UACf,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,MAAM,CAAC;AAE3D,MAAM,QAAQ,MAA4D,YACxE,IAAI,mBAAmB;CAAE;CAAM;CAAS,OAAO,IAAI,MAAM,QAAQ;CAAE,CAAC;AAEtE,MAAM,YAAY,UAChB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,MAAM;AAEtE,MAAM,gBAAgB,OAAgC,YAAmC;CACvF,MAAM,OAAO,OAAO,KAAK,MAAM;AAC/B,QACE,KAAK,WAAW,QAAQ,QAAQ,QAAQ,OAAO,MAAM,CAAC,UACtD,KAAK,OAAO,QAAQ,QAAQ,SAAS,IAAI,CAAC;;AAI9C,MAAM,gBAAgB,UAA2B;AAC/C,KAAI,OAAO,UAAU,YAAY,MAAM,WAAW,KAAK,MAAM,MAAM,KAAK,MACtE,OAAM,KAAK,0BAA0B,gDAAgD;AAEvF,QAAO;;AAGT,MAAM,kBAAkB,UACtB,OAAO,IAAI,aAAa;CACtB,MAAM,UAAU,OAAO,OAAO,IAAI;EAChC,WAAW;AACT,OAAI,OAAO,UAAU,SAAU,QAAO,EAAE,MAAM,aAAa,MAAM,EAAE;AACnE,OAAI,CAAC,SAAS,MAAM,IAAI,CAAC,aAAa,OAAO,CAAC,QAAQ,YAAY,CAAC,CACjE,OAAM,KACJ,0BACA,2FACD;AAEH,UAAO;IAAE,MAAM,aAAa,MAAM,KAAK;IAAE,WAAW,MAAM;IAAW;;EAEvE,QAAQ,UACN,iBAAiB,qBACb,QACA,KAAK,0BAA0B,kCAAkC;EACxE,CAAC;AACF,KAAI,EAAE,eAAe,YAAY,QAAQ,cAAc,OACrD,QAAO,EAAE,MAAM,QAAQ,MAAM;CAE/B,MAAM,iBAAiB,OAAO,MAAM,eAAe,WAAW,QAAQ,UAAU,CAAC,KAC/E,OAAO,UACJ,UACC,IAAI,mBAAmB;EACrB,MAAM;EACN,SAAS;EACT;EACD,CAAC,CACL,CACF;AACD,QAAO;EAAE,MAAM,QAAQ;EAAM;EAAgB;EAC7C;;AAGJ,MAAa,qBACX,cAEA,OAAO,IAAI,aAAa;CACtB,MAAM,MAAM,OAAO,OAAO,eAAe,mBAAmB,cAAc,CAAC,KACzE,OAAO,UACJ,UACC,IAAI,mBAAmB;EACrB,MAAM;EACN,SAAS,GAAG,mBAAmB,cAAc;EAC7C,OAAO,QAAQ,MAAM;EACtB,CAAC,CACL,CACF;AAUD,MATkB,OAAO,OAAO,IAAI;EAClC,WAAW,qBAAqB,IAAI;EACpC,QAAQ,UACN,IAAI,mBAAmB;GACrB,MAAM;GACN,SAAS;GACT,OAAO,QAAQ,MAAM;GACtB,CAAC;EACL,CAAC,MACgB,OAChB,QAAO,OAAO,OAAO,KACnB,KAAK,0BAA0B,qDAAqD,CACrF;CAEH,MAAM,UAAU,OAAO,OAAO,oBAAoB,kBAAkB,CAAC,IAAI,CAAC,KACxE,OAAO,UACJ,UACC,IAAI,mBAAmB;EACrB,MAAM;EACN,SAAS;EACT,OAAO,QAAQ,MAAM;EACtB,CAAC,CACL,CACF;CAED,MAAM,WAAW,IAAI,IAAI,UAAU,UAAU,KAAK,aAAa,SAAS,KAAK,CAAC;CAC9E,MAAM,SAAS,OAAO,KAAK,QAAQ;CACnC,MAAM,UAAU,CAAC,GAAG,SAAS,CAAC,QAAQ,SAAS,EAAE,QAAQ,SAAS;CAClE,MAAM,UAAU,OAAO,QAAQ,SAAS,CAAC,SAAS,IAAI,KAAK,CAAC;AAC5D,KAAI,QAAQ,SAAS,KAAK,QAAQ,SAAS,EACzC,QAAO,OAAO,OAAO,KACnB,KACE,2BACA,oEAAoE,QAAQ,KAAK,KAAK,IAAI,OAAO,uBAAuB,QAAQ,OAAO,GACxI,CACF;CAEH,MAAM,UAAU,OAAO,OAAO,QAAQ,SAAS,SAC7C,eAAe,QAAQ,MAAM,CAAC,KAAK,OAAO,KAAK,YAAY,CAAC,MAAM,QAAQ,CAAU,CAAC,CACtF;AACD,QAAO,OAAO,YAAY,QAAQ;EAClC"}

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

@@ -1,6 +1,6 @@
 import { t as __export } from "./chunk-Bp6m_JJh.js";
-import { n as PlatformRuntimeKey } from "./constants-BRhIX_rz.js";
-import { Cause, Config, Context, Effect, Layer, Metric, Option } from "effect";
+import { n as PlatformRuntimeKey } from "./constants-D113Ut1x.js";
+import { Cause, Config, Effect, Layer, Metric, Option } from "effect";
 import { Headers } from "effect/unstable/http";
 import * as Observability from "effect/unstable/observability";
 
@@ -9,6 +9,7 @@ var telemetry_exports = /* @__PURE__ */ __export({
 	Attr: () => Attr,
 	EventAttr: () => EventAttr,
 	EventName: () => EventName,
+	ResourceAttr: () => ResourceAttr,
 	SpanName: () => SpanName,
 	addCurrentSpanEvent: () => addCurrentSpanEvent,
 	annotateError: () => annotateError,
@@ -35,7 +36,11 @@ const Attr = {
 	resourceName: "airfoil.resource.name",
 	resourceSource: "airfoil.resource.source",
 	batchMutations: "airfoil.batch.mutations",
+	batchOutcome: "airfoil.batch.outcome",
 	webhookPath: "airfoil.webhook.path",
+	webhookOutcome: "airfoil.webhook.outcome",
+	syncState: "airfoil.connector.sync.state",
+	apiRetryReason: "airfoil.connector.api.retry.reason",
 	publisherSuccess: "airfoil.publisher.success",
 	stateKey: "airfoil.state.key",
 	apiPath: "airfoil.api.path",
@@ -44,6 +49,12 @@ const Attr = {
 	errorMessage: "airfoil.error.message",
 	errorDetails: "airfoil.error.details"
 };
+/** Resource attributes injected by the hosted operator through standard OTel environment keys. */
+const ResourceAttr = {
+	serviceInstanceId: "service.instance.id",
+	connectorRevision: "airfoil.connector.revision",
+	teamId: "airfoil.team.id"
+};
 /** Span event names for high-cardinality reproduction details. */
 const EventName = { batchCheckpoint: "airfoil.batch.checkpoint" };
 /** Event-only attributes. These are intentionally not span attributes. */
@@ -165,6 +176,7 @@ const layerOtlpTracing = (options = {}) => Layer.unwrap(Effect.gen(function* ()
 		headers: Option.isSome(raw.rawHeaders) ? parseOtelHeaders(raw.rawHeaders.value) : void 0
 	}, options);
 }));
+/** Exports connector metrics over OTLP when telemetry is enabled. */
 const layerOtlpMetrics = (options = {}) => Layer.unwrap(Effect.gen(function* () {
 	const raw = yield* OtlpEnvConfig;
 	if (!raw.enabled) return Layer.empty;
@@ -177,15 +189,13 @@ const layerOtlpMetrics = (options = {}) => Layer.unwrap(Effect.gen(function* ()
 		temporality: "cumulative"
 	}).pipe(Layer.provide(Observability.OtlpSerialization.layerJson));
 }));
+/** Enables OTLP traces and metrics with shared environment configuration. */
 const layerOtlp = (options = {}) => Layer.mergeAll(layerOtlpTracing(options), layerOtlpMetrics(options));
+/** Periodically logs the in-memory metric snapshot for local debugging. */
 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 { 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
+export { addCurrentSpanEvent as a, SpanName as i, EventAttr as n, annotateError as o, EventName as r, telemetry_exports as s, Attr as t };
+//# sourceMappingURL=telemetry-j_nxwYfh.js.map

package/dist/telemetry-j_nxwYfh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-j_nxwYfh.js","names":["defaultRedactedHeaders: ReadonlyArray<string | RegExp>"],"sources":["../src/telemetry.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  batchOutcome: \"airfoil.batch.outcome\",\n  webhookPath: \"airfoil.webhook.path\",\n  webhookOutcome: \"airfoil.webhook.outcome\",\n  syncState: \"airfoil.connector.sync.state\",\n  apiRetryReason: \"airfoil.connector.api.retry.reason\",\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/** Resource attributes injected by the hosted operator through standard OTel environment keys. */\nexport const ResourceAttr = {\n  serviceInstanceId: \"service.instance.id\",\n  connectorRevision: \"airfoil.connector.revision\",\n  teamId: \"airfoil.team.id\",\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\n/** OTLP metric export settings. */\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\n/** Exports connector metrics over OTLP when telemetry is enabled. */\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\n/** Enables OTLP traces and metrics with shared environment configuration. */\nexport const layerOtlp = (options: OtlpTracingOptions & OtlpMetricsOptions = {}) =>\n  Layer.mergeAll(layerOtlpTracing(options), layerOtlpMetrics(options));\n\n/** Periodically logs the in-memory metric snapshot for local debugging. */\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"],"mappings":"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"}

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

@@ -1,4 +1,4 @@
-import { t as ConnectorError } from "./index-D54ySAKn.js";
+import { t as ConnectorError } from "./index-DKoRwyFn.js";
 import { Duration, Effect, Schema } from "effect";
 import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
 
@@ -171,4 +171,4 @@ type ConnectorDefinition<Resources extends ReadonlyArray<ResourceDefinition> = R
 };
 //#endregion
 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
+//# sourceMappingURL=types-jVD5Ys43.d.ts.map

package/dist/webhook/index.d.ts

@@ -1,6 +1,7 @@
-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";
+import "../index-DKoRwyFn.js";
+import { C as WebhookRouteInput, S as WebhookRouteContext, x as WebhookRoute, y as WebhookAckMode } from "../types-jVD5Ys43.js";
+import "../service-CUjGhe-7.js";
+import "../index-ZSuiZX5H.js";
+import "../index-BA8ASHKr.js";
+import { n as route, r as router } from "../index-BKw7jA2a.js";
 export { WebhookAckMode, WebhookRoute, WebhookRouteContext, WebhookRouteInput, route, router };

package/dist/webhook/index.js

@@ -1,8 +1,9 @@
 import "../errors-DHWylqRZ.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";
+import "../constants-D113Ut1x.js";
+import "../telemetry-j_nxwYfh.js";
+import "../metrics-inkCAxKq.js";
+import "../service-DiP-XETo.js";
+import { n as router } from "../server-D-eLX3yN.js";
+import { t as route } from "../webhook-MhFcLW-o.js";
 
 export { route, router };

package/dist/{webhook-DI-Afxkg.js → webhook-MhFcLW-o.js}

@@ -1,5 +1,5 @@
 import { t as __export } from "./chunk-Bp6m_JJh.js";
-import { n as router } from "./server-CXTQ7odl.js";
+import { n as router } from "./server-D-eLX3yN.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-DI-Afxkg.js.map
+//# sourceMappingURL=webhook-MhFcLW-o.js.map

package/dist/{webhook-DI-Afxkg.js.map → webhook-MhFcLW-o.js.map}

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"webhook-MhFcLW-o.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.5.3",
+  "version": "0.6.0",
   "repository": "useairfoil/typescript-sdk",
   "files": [
     "dist",
@@ -82,7 +82,7 @@
   "dependencies": {
     "@effect/platform-node": "^4.0.0-rc.108",
     "@useairfoil/flight": "0.4.6",
-    "@useairfoil/wings": "0.4.4"
+    "@useairfoil/wings": "0.4.5"
   },
   "devDependencies": {
     "@effect/sql-pg": "^4.0.0-rc.108",

package/src/metrics.ts

@@ -2,6 +2,8 @@ import { DateTime, Effect, Metric, Option } from "effect";
 
 import type { SyncState } from "./core/types";
 
+import { Attr } from "./telemetry";
+
 export type BatchSource = "backfill" | "changes" | "webhook";
 export type BatchOutcome = "accepted" | "rejected" | "error";
 export type ApiRetryReason = "transport" | "timeout" | "rate_limit" | "server_error";
@@ -41,61 +43,89 @@ export type ApiRetryMetricAttrs = {
   readonly reason: ApiRetryReason;
 };
 
-export const entitiesUpsertedTotal = Metric.counter("airfoil_connector_entities_upserted_total", {
+export const entitiesUpserted = Metric.counter("airfoil.connector.entity.upserts", {
   description: "Total entity upsert mutations published by connector sources",
   incremental: true,
+  attributes: { unit: "{mutation}" },
 });
 
-export const entitiesDeletedTotal = Metric.counter("airfoil_connector_entities_deleted_total", {
+export const entitiesDeleted = Metric.counter("airfoil.connector.entity.deletes", {
   description: "Total entity delete mutations published by connector sources",
   incremental: true,
+  attributes: { unit: "{mutation}" },
 });
 
-export const batchesTotal = Metric.counter("airfoil_connector_batches_total", {
+export const batches = Metric.counter("airfoil.connector.batches", {
   description: "Total resource batches published by connector sources",
   incremental: true,
+  attributes: { unit: "{batch}" },
 });
 
-export const batchSize = Metric.histogram("airfoil_connector_batch_size", {
+export const batchSize = Metric.histogram("airfoil.connector.batch.size", {
   description: "Distribution of resource mutation batch sizes",
   boundaries: [1, 5, 10, 25, 50, 100, 250, 500, 1000],
+  attributes: { unit: "{mutation}" },
 });
 
-export const publishDuration = Metric.timer("airfoil_connector_publish_duration_ms", {
+export const publishDuration = Metric.timer("airfoil.connector.publish.duration", {
   description: "Publisher call duration in milliseconds",
   boundaries: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000],
+  attributes: { unit: "ms" },
 });
 
-export const webhookRequestsTotal = Metric.counter("airfoil_connector_webhook_requests_total", {
+export const webhookRequests = Metric.counter("airfoil.connector.webhook.requests", {
   description: "Total webhook HTTP requests handled by connector routes",
   incremental: true,
+  attributes: { unit: "{request}" },
 });
 
-export const webhookQueueDepth = Metric.gauge("airfoil_connector_webhook_queue_depth", {
+export const webhookQueueDepth = Metric.gauge("airfoil.connector.webhook.queue.depth", {
   description: "Current queued webhook batches waiting for publish",
+  attributes: { unit: "{batch}" },
 });
 
-export const syncState = Metric.gauge("airfoil_connector_sync_state", {
+export const syncState = Metric.gauge("airfoil.connector.sync.state", {
   description: "Connector resource sync state as a Prometheus state-set gauge",
+  attributes: { unit: "1" },
 });
 
-export const lastSuccessTimestamp = Metric.gauge(
-  "airfoil_connector_last_success_timestamp_seconds",
-  {
-    description: "Unix timestamp of the last successful durable source checkpoint",
-  },
-);
+export const lastSuccessTimestamp = Metric.gauge("airfoil.connector.last_success.timestamp", {
+  description: "Unix timestamp of the last successful durable source checkpoint",
+  attributes: { unit: "s" },
+});
 
-export const apiRetriesTotal = Metric.counter("airfoil_connector_api_retries_total", {
+export const apiRetries = Metric.counter("airfoil.connector.api.retries", {
   description: "Total provider API retries performed by the connector",
   incremental: true,
+  attributes: { unit: "{retry}" },
+});
+
+const resourceAttributes = (attrs: ResourceMetricAttrs) => ({
+  [Attr.connectorName]: attrs.connector,
+  [Attr.resourceName]: attrs.resource,
+  [Attr.resourceSource]: attrs.source,
+});
+
+const syncAttributes = (attrs: SyncStateAttrs) => ({
+  [Attr.connectorName]: attrs.connector,
+  [Attr.resourceName]: attrs.resource,
 });
 
 export const recordWebhookRequest = (attrs: WebhookMetricAttrs) =>
-  Metric.update(Metric.withAttributes(webhookRequestsTotal, attrs), 1);
+  Metric.update(
+    Metric.withAttributes(webhookRequests, {
+      [Attr.connectorName]: attrs.connector,
+      [Attr.webhookPath]: attrs.path,
+      [Attr.webhookOutcome]: attrs.outcome,
+    }),
+    1,
+  );
 
 export const setWebhookQueueDepth = (connector: string, depth: number) =>
-  Metric.update(Metric.withAttributes(webhookQueueDepth, { connector }), depth);
+  Metric.update(
+    Metric.withAttributes(webhookQueueDepth, { [Attr.connectorName]: connector }),
+    depth,
+  );
 
 export const setLastSuccessTimestamp = (attrs: LastSuccessMetricAttrs, lastSuccessAt?: string) => {
   const timestamp =
@@ -105,11 +135,24 @@ export const setLastSuccessTimestamp = (attrs: LastSuccessMetricAttrs, lastSucce
           Option.map((dateTime) => DateTime.toEpochMillis(dateTime) / 1000),
           Option.getOrElse(() => 0),
         );
-  return Metric.update(Metric.withAttributes(lastSuccessTimestamp, attrs), timestamp);
+  return Metric.update(
+    Metric.withAttributes(lastSuccessTimestamp, {
+      [Attr.connectorName]: attrs.connector,
+      [Attr.resourceName]: attrs.resource,
+      [Attr.resourceSource]: attrs.source,
+    }),
+    timestamp,
+  );
 };
 
 export const recordApiRetry = (attrs: ApiRetryMetricAttrs) =>
-  Metric.update(Metric.withAttributes(apiRetriesTotal, attrs), 1);
+  Metric.update(
+    Metric.withAttributes(apiRetries, {
+      [Attr.connectorName]: attrs.connector,
+      [Attr.apiRetryReason]: attrs.reason,
+    }),
+    1,
+  );
 
 const syncStates = ["pending", "backfilling", "live", "error"] as const;
 
@@ -119,10 +162,13 @@ export const setSyncState = (attrs: SyncStateAttrs, current: SyncState) =>
     (state) =>
       Metric.update(
         Metric.withAttributes(syncState, {
-          ...attrs,
-          state,
+          ...syncAttributes(attrs),
+          [Attr.syncState]: state,
         }),
         state === current ? 1 : 0,
       ),
     { discard: true },
   );
+
+/** @internal Converts the ergonomic SDK input to canonical OTel attributes. */
+export const withResourceAttributes = resourceAttributes;

package/src/publisher/index.ts

@@ -4,4 +4,4 @@ export type { WingsPublisherConfig } from "./wings";
 
 export { layerConsole } from "./console";
 export { Publisher } from "./service";
-export { layerWings } from "./wings";
+export { layerWings, layerWingsConfig } from "./wings";

package/src/publisher/instrumented.ts

@@ -18,28 +18,35 @@ export const publishBatch = Effect.fnUntraced(function* (options: {
     resource: options.resource,
     source: options.source,
   };
+  const metricAttributes = Metrics.withResourceAttributes(metric);
   const upserts = options.batch.mutations.filter((mutation) => mutation.op === "upsert").length;
   const deletes = options.batch.mutations.length - upserts;
 
   const publisher = yield* Publisher;
-  const [duration, ack] = yield* Effect.timed(
-    publisher.publish({
+  const ack = yield* publisher
+    .publish({
       resource: options.resource,
       source: options.source,
       batch: options.batch,
-    }),
-  ).pipe(
-    Effect.catchCause((cause) =>
-      Metric.update(
-        Metric.withAttributes(Metrics.batchesTotal, { ...metric, outcome: "error" }),
-        1,
-      ).pipe(Effect.andThen(Effect.failCause(cause))),
-    ),
-  );
+    })
+    .pipe(
+      Effect.trackDuration(Metric.withAttributes(Metrics.publishDuration, metricAttributes)),
+      Effect.catchCause((cause) =>
+        Metric.update(
+          Metric.withAttributes(Metrics.batches, {
+            ...metricAttributes,
+            [Attr.batchOutcome]: "error",
+          }),
+          1,
+        ).pipe(Effect.andThen(Effect.failCause(cause))),
+      ),
+    );
 
-  yield* Metric.update(Metric.withAttributes(Metrics.publishDuration, metric), duration);
   yield* Metric.update(
-    Metric.withAttributes(Metrics.batchesTotal, { ...metric, outcome: ack.status }),
+    Metric.withAttributes(Metrics.batches, {
+      ...metricAttributes,
+      [Attr.batchOutcome]: ack.status,
+    }),
     1,
   );
 
@@ -53,10 +60,10 @@ export const publishBatch = Effect.fnUntraced(function* (options: {
     );
   }
 
-  yield* Metric.update(Metric.withAttributes(Metrics.entitiesUpsertedTotal, metric), upserts);
-  yield* Metric.update(Metric.withAttributes(Metrics.entitiesDeletedTotal, metric), deletes);
+  yield* Metric.update(Metric.withAttributes(Metrics.entitiesUpserted, metricAttributes), upserts);
+  yield* Metric.update(Metric.withAttributes(Metrics.entitiesDeleted, metricAttributes), deletes);
   yield* Metric.update(
-    Metric.withAttributes(Metrics.batchSize, metric),
+    Metric.withAttributes(Metrics.batchSize, metricAttributes),
     options.batch.mutations.length,
   );
 

package/src/publisher/wings.ts

@@ -4,16 +4,19 @@ import { Effect, Layer } from "effect";
 import type { ConnectorDefinition, ResourceDefinition } from "../core/types";
 
 import { ConnectorError } from "../errors";
+import { loadTableBindings } from "../runtime-config/table-bindings";
 import { SpanName } from "../telemetry";
 import { Publisher, type PublishAck, type PublisherService } from "./service";
 
 type Rows = Record<string, unknown>;
 
+/** Programmatic mapping between a connector resource and a Wings table. */
 export type WingsTableMapping = {
   readonly name: string;
   readonly partitionValue?: Wings.PartitionValue.PartitionValue;
 };
 
+/** Direct Wings publisher configuration, mainly for tests and local runtimes. */
 export type WingsPublisherConfig = {
   readonly connector: ConnectorDefinition;
   readonly tables: Record<string, string | WingsTableMapping>;
@@ -48,7 +51,6 @@ const validateTableMapping = (options: {
     try: () => {
       const keyField = Wings.TableUtils.getKeyField(options.table);
       const versionField = Wings.TableUtils.getVersionField(options.table);
-      const partitionField = Wings.TableUtils.getPartitionField(options.table);
 
       if (keyField.name !== options.resource.key) {
         throw new Error(
@@ -63,16 +65,7 @@ const validateTableMapping = (options: {
       if (options.resource.partition?.required === true && !options.partitionValue) {
         throw new Error(`Resource ${options.resource.name} requires a partition value`);
       }
-      if (partitionField && !options.partitionValue) {
-        throw new Error(
-          `Wings table ${options.table.name} is partitioned but no partition value was provided`,
-        );
-      }
-      if (!partitionField && options.partitionValue) {
-        throw new Error(
-          `Wings table ${options.table.name} is not partitioned but a partition value was provided`,
-        );
-      }
+      Wings.TableUtils.validatePartitionValueUnsafe(options.table, options.partitionValue);
 
       return { keyField, versionField };
     },
@@ -97,6 +90,7 @@ const rejected = (entry: PublisherEntry, reason: string, rejectedRows: number):
   partition: entry.partitionValue,
 });
 
+/** Builds a Wings publisher from explicit table mappings. */
 export const layerWings = (
   config: WingsPublisherConfig,
 ): Layer.Layer<Publisher, ConnectorError, Wings.WingsClient.WingsClient> =>
@@ -202,3 +196,9 @@ export const layerWings = (
       return Publisher.of(service);
     }),
   );
+
+/** Builds a Wings publisher from the complete hosted `AIRFOIL_TABLE_BINDINGS` document. */
+export const layerWingsConfig = (connector: ConnectorDefinition) =>
+  Layer.unwrap(
+    loadTableBindings(connector).pipe(Effect.map((tables) => layerWings({ connector, tables }))),
+  );

package/src/runtime-config/config.ts

@@ -0,0 +1,16 @@
+import type { WingsClientOptions } from "@useairfoil/wings/wings-client";
+
+import { Config } from "effect";
+
+import { PlatformRuntimeDefault, PlatformRuntimeKey } from "./constants";
+
+/** Shared HTTP port used by hosted and sandbox connector entrypoints. */
+export const httpPort = Config.port(PlatformRuntimeKey.httpPort).pipe(
+  Config.withDefault(PlatformRuntimeDefault.httpPort),
+);
+
+/** Shared Wings client configuration supplied by the hosting platform. */
+export const wingsClient = {
+  host: Config.nonEmptyString(PlatformRuntimeKey.wingsHost),
+  namespace: Config.nonEmptyString(PlatformRuntimeKey.wingsNamespace),
+} satisfies Config.Wrap<WingsClientOptions>;

package/src/runtime-config/constants.ts

@@ -3,6 +3,8 @@ import { HashSet } from "effect";
 /** Shared runtime keys owned by Airfoil rather than an individual connector. */
 export const PlatformRuntimeKey = {
   configPath: "AIRFOIL_CONFIG_PATH",
+  httpPort: "AIRFOIL_HTTP_PORT",
+  tableBindings: "AIRFOIL_TABLE_BINDINGS",
   connectorInstanceId: "AIRFOIL_CONNECTOR_INSTANCE_ID",
   stateTable: "AIRFOIL_STATE_TABLE",
   postgresConnectionString: "POSTGRES_CONNECTION_STRING",
@@ -18,6 +20,7 @@ export const PlatformRuntimeKey = {
 
 /** Defaults for optional platform-owned runtime configuration. */
 export const PlatformRuntimeDefault = {
+  httpPort: 8080,
   stateTable: "_airfoil_connectors_state",
 } as const;