@fluid-app/droplet-sdk 0.2.70 → 0.2.71

package/README.md

@@ -167,14 +167,94 @@ resolve: async ({ dri }) => {
 },
 ```
 
+## Reading status and receiving reconcile events
+
+```ts
+import { createFluidInstallationClient } from "@fluid-app/droplet-sdk";
+
+const client = createFluidInstallationClient({ installToken, baseUrl });
+const result = await client.getInstallationStatus();
+if (result.ok) console.log(result.status.droplet_installation_status);
+```
+
+```ts
+import {
+  createInMemoryReconcileDedupe,
+  withFluidReconcileEvents,
+} from "@fluid-app/droplet-sdk/next";
+export const POST = withFluidReconcileEvents(
+  async (event) => {
+    await handleReconcile(event);
+  },
+  { secret: webhookSecret, dedupe: createInMemoryReconcileDedupe() },
+);
+```
+
+Use the droplet's own webhook secret. `dedupe` is required; there is no default
+store. The explicit in-memory store above is per-process and suitable for a
+single instance. Across instances, a shared store implementing atomic
+`claim`, `complete` and `release` is required (for example Redis `SET NX PX`
+with atomic token checks for completion and release).
+The claim methods may return synchronously or as promises:
+
+```ts
+type ReconcileClaim =
+  | { status: "claimed"; token: string }
+  | { status: "in_flight" }
+  | { status: "done" };
+
+claim(id: string, ttlMs: number): ReconcileClaim | Promise<ReconcileClaim>;
+complete(id: string, token: string, ttlMs: number): void | Promise<void>;
+release(id: string, token: string): void | Promise<void>;
+```
+
+`claim` must atomically reserve an available id with a fresh token. Its `ttlMs`
+is the in-flight lease only: `Math.min(inFlightTtlMs, dedupeTtlMs)`.
+The wrapper's `inFlightTtlMs` defaults to 60,000 ms and must be positive and finite; keep it under about 10 minutes, the span of Fluid's
+retries, or a crashed instance's lease can outlast every retry. `dedupeTtlMs` must
+also be positive and finite.
+An active
+claim returns `in_flight`: the wrapper responds 503 (a 4xx would be recorded by Fluid as a permanent rejection) `{ error: "in flight" }`
+without calling the handler, so Fluid retries later. A completed delivery returns
+`done`: the wrapper responds 200 `{ ok: true, duplicate: true }`.
+A throwing claim returns a retryable 500 without running the handler.
+
+Implement `complete` and `release` alongside `claim`. After an ok handler response,
+`complete(id, token, ttlMs)` receives `dedupeTtlMs` for done retention from
+completion (default 86,400,000 ms). On a throw
+or non-ok response, `release(id, token)` frees the claim so a retry can run.
+Both operations must atomically check that the token still owns an unexpired
+claim; otherwise they do nothing. After expiry, a new delivery can claim the id
+with a new token, and the old handler cannot complete or release its claim.
+Completion and release failures are logged with the event id only and preserve
+the handler's response (or 500 for a thrown handler).
+
+The explicit in-memory store implements all three operations. It also caps leases
+by its own `inFlightTtlMs` option (default 60,000 ms). For longer handlers, set
+`inFlightTtlMs` on both the wrapper and `createInMemoryReconcileDedupe`.
+
+After signature verification and JSON parsing, unknown `reconcile.*` event kinds
+return 200 `{ ok: true, ignored: true }` without claiming or calling the handler.
+Only the event name is logged. Non-reconcile or missing event names still return
+400 for invalid payloads.
+
+Only atomic stores are accepted: `seen`/`mark` stores are not supported, because
+they cannot exclude concurrent deliveries of one event id. A shared atomic store
+(for example Redis or a database row with a unique id) is required for
+multi-instance deployments; `createInMemoryReconcileDedupe()` is per process and
+suits a single instance only. Keep handlers idempotent, including for retries after
+TTL expiry or bounded in-memory eviction.
+Bodies are limited to 1,048,576 bytes before signature verification; configure
+`maxBodyBytes` to change this limit.
+
 ## Exports
 
-| Subpath    | Contents                                                                                                               |
-| ---------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `.`        | `verifySignature`, `tokenDigest`, `backfillCallbackTokens`, `describeError`, store types                               |
-| `/next`    | `withFluidCallback`, `withFluidWebhook`                                                                                |
-| `/prisma`  | `createPrismaCallbackStore`                                                                                            |
-| `/drizzle` | `createDrizzleCallbackStore` — structurally typed, takes `eq` injected, so this package never depends on `drizzle-orm` |
+| Subpath    | Contents                                                                                                                                                        |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.`        | `verifySignature`, `tokenDigest`, `backfillCallbackTokens`, `describeError`, `createFluidInstallationClient`, status schemas/types, health helpers, store types |
+| `/next`    | `withFluidCallback`, `withFluidWebhook`, `withFluidReconcileEvents`, `createInMemoryReconcileDedupe`, reconcile schemas/types                                   |
+| `/prisma`  | `createPrismaCallbackStore`                                                                                                                                     |
+| `/drizzle` | `createDrizzleCallbackStore` — structurally typed, takes `eq` injected, so this package never depends on `drizzle-orm`                                          |
 
 ## License
 

package/dist/health.d.mts

@@ -0,0 +1,22 @@
+import { Logger } from "./redact.mjs";
+import { InstallationHealth } from "./installation.mjs";
+
+//#region src/health.d.ts
+/** Describes changes to the health verdict and signals. */
+declare function describeHealthTransition(previous: InstallationHealth, current: InstallationHealth): {
+  from: string;
+  to: string;
+  changedSignals: (keyof InstallationHealth["signals"])[];
+} | null;
+/** Logs a redacted health transition at its severity. */
+declare function logHealthTransition({
+  previous,
+  current,
+  logger
+}: {
+  previous: InstallationHealth;
+  current: InstallationHealth;
+  logger?: Logger;
+}): void;
+//#endregion
+export { describeHealthTransition, logHealthTransition };

package/dist/health.mjs

@@ -0,0 +1,28 @@
+import { consoleLogger, redactValue } from "./redact.mjs";
+//#region src/health.ts
+function describeHealthTransition(previous, current) {
+	const changedSignals = Object.keys(current.signals).filter((key) => JSON.stringify(previous.signals[key]) !== JSON.stringify(current.signals[key]));
+	return previous.verdict === current.verdict && changedSignals.length === 0 ? null : {
+		from: previous.verdict,
+		to: current.verdict,
+		changedSignals
+	};
+}
+function logHealthTransition({ previous, current, logger = consoleLogger }) {
+	const transition = describeHealthTransition(previous, current);
+	if (!transition) return;
+	const severity = {
+		unknown: 2,
+		idle: 2,
+		healthy: 2,
+		degraded: 3,
+		failing: 4
+	};
+	logger[(severity[current.verdict] ?? 1) > (severity[previous.verdict] ?? 1) ? "warn" : "info"]("[fluid-health] health changed", redactValue({
+		...transition,
+		previous,
+		current
+	}));
+}
+//#endregion
+export { describeHealthTransition, logHealthTransition };

package/dist/index.d.mts

@@ -3,4 +3,6 @@ import { MAX_SIGNATURE_AGE_SECONDS, SignatureFailureReason, SignatureResult, Ver
 import { Logger, consoleLogger, describeError, redactValue } from "./redact.mjs";
 import { BackfillResult, CallbackListingClient, backfillCallbackTokens } from "./backfill.mjs";
 import { CallbackVerificationReadiness, reportCallbackVerificationReadiness } from "./readiness.mjs";
-export { type BackfillResult, type CallbackListingClient, type CallbackTokenStore, type CallbackVerificationReadiness, type Logger, MAX_SIGNATURE_AGE_SECONDS, type SignatureFailureReason, type SignatureResult, type StoredRegistration, type VerifySignatureInput, backfillCallbackTokens, consoleLogger, describeError, redactValue, reportCallbackVerificationReadiness, tokenDigest, verifySignature };
+import { FluidInstallationClient, FluidInstallationClientOptions, InstallationHealth, InstallationStatusResult, ParsedStatus, ReconcileResource, createFluidInstallationClient, installationHealthSchema, installationStatusSchema, reconcileResourceSchema } from "./installation.mjs";
+import { describeHealthTransition, logHealthTransition } from "./health.mjs";
+export { type BackfillResult, type CallbackListingClient, type CallbackTokenStore, type CallbackVerificationReadiness, FluidInstallationClient, FluidInstallationClientOptions, InstallationHealth, InstallationStatusResult, type Logger, MAX_SIGNATURE_AGE_SECONDS, ParsedStatus, ReconcileResource, type SignatureFailureReason, type SignatureResult, type StoredRegistration, type VerifySignatureInput, backfillCallbackTokens, consoleLogger, createFluidInstallationClient, describeError, describeHealthTransition, installationHealthSchema, installationStatusSchema, logHealthTransition, reconcileResourceSchema, redactValue, reportCallbackVerificationReadiness, tokenDigest, verifySignature };

package/dist/index.mjs

@@ -2,4 +2,6 @@ import { MAX_SIGNATURE_AGE_SECONDS, tokenDigest, verifySignature } from "./signa
 import { consoleLogger, describeError, redactValue } from "./redact.mjs";
 import { backfillCallbackTokens } from "./backfill.mjs";
 import { reportCallbackVerificationReadiness } from "./readiness.mjs";
-export { MAX_SIGNATURE_AGE_SECONDS, backfillCallbackTokens, consoleLogger, describeError, redactValue, reportCallbackVerificationReadiness, tokenDigest, verifySignature };
+import { createFluidInstallationClient, installationHealthSchema, installationStatusSchema, reconcileResourceSchema } from "./installation.mjs";
+import { describeHealthTransition, logHealthTransition } from "./health.mjs";
+export { MAX_SIGNATURE_AGE_SECONDS, backfillCallbackTokens, consoleLogger, createFluidInstallationClient, describeError, describeHealthTransition, installationHealthSchema, installationStatusSchema, logHealthTransition, reconcileResourceSchema, redactValue, reportCallbackVerificationReadiness, tokenDigest, verifySignature };

package/dist/installation.d.mts

@@ -0,0 +1,106 @@
+import { z } from "zod";
+
+//#region src/installation.d.ts
+declare const installationHealthSchema: z.ZodType<InstallationHealth>;
+declare const reconcileResourceSchema: z.ZodType<ReconcileResource>;
+declare const installationStatusSchema: z.ZodType<ParsedStatus>;
+type StatusSection<T> = {
+  available: boolean;
+  error: {
+    type: string;
+    description: string;
+  } | null;
+  data: T | null;
+};
+type StateSignal = {
+  state: string;
+  observed_at: string | null;
+};
+type InstallationHealth = {
+  verdict: string;
+  signals: {
+    callback: {
+      verdict: string;
+    };
+    breaker: StateSignal;
+    lifecycle: StateSignal;
+  };
+};
+type ReconcileResource = {
+  kind: string;
+  key: string;
+  status: string;
+  error_code: string | null;
+};
+type ParsedStatus = {
+  droplet_installation_status: {
+    generated_at: string;
+    sections: {
+      install_status: StatusSection<{
+        status: string;
+        delivery_state: string | null;
+      }>;
+      lifecycle: StatusSection<{
+        deliveries: {
+          [key: string]: unknown;
+          event: string;
+          trigger: string;
+          state: string;
+          attempts: number;
+          last_status: number | string | null;
+          last_error_category?: string | null;
+          created_at?: string;
+          updated_at?: string;
+        }[];
+      }>;
+      health: StatusSection<InstallationHealth>;
+      reconcile: StatusSection<{
+        pinned_version: number | null;
+        target_version: number | null;
+        state: string;
+        resources: ReconcileResource[];
+        truncated: boolean;
+        grants: {
+          count: number;
+        };
+        pending: {
+          count: number;
+        };
+      }>;
+    };
+  };
+  status: 200;
+  meta: {
+    request_uuid: string | null;
+    timestamp: string;
+  };
+};
+type InstallationStatusResult = {
+  ok: true;
+  status: ParsedStatus;
+} | {
+  ok: false;
+  error: {
+    code: "unauthorized" | "forbidden" | "invalid_response" | "http_error" | "network" | "timeout";
+    httpStatus?: number;
+    message: string;
+  };
+};
+interface FluidInstallationClientOptions {
+  installToken: string;
+  baseUrl: string;
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+}
+interface FluidInstallationClient {
+  getInstallationStatus(): Promise<InstallationStatusResult>;
+}
+/** Creates a client for the calling installation's status. */
+declare function createFluidInstallationClient({
+  installToken,
+  baseUrl,
+  fetch: fetcher,
+  timeoutMs
+}: FluidInstallationClientOptions): FluidInstallationClient;
+//#endregion
+export { FluidInstallationClient, FluidInstallationClientOptions, InstallationHealth, InstallationStatusResult, ParsedStatus, ReconcileResource, createFluidInstallationClient, installationHealthSchema, installationStatusSchema, reconcileResourceSchema };

package/dist/installation.mjs

@@ -0,0 +1,122 @@
+import { z } from "zod";
+//#region src/installation.ts
+const section = (data) => z.object({
+	available: z.boolean(),
+	error: z.object({
+		type: z.string(),
+		description: z.string()
+	}).nullable(),
+	data: data.nullable()
+});
+const stateSignal = z.object({
+	state: z.string(),
+	observed_at: z.string().nullable()
+});
+const installationHealthSchema = z.object({
+	verdict: z.string(),
+	signals: z.object({
+		callback: z.object({ verdict: z.string() }),
+		breaker: stateSignal,
+		lifecycle: stateSignal
+	})
+});
+const reconcileResourceSchema = z.object({
+	kind: z.string(),
+	key: z.string(),
+	status: z.string(),
+	error_code: z.string().nullable()
+});
+const installationStatusSchema = z.object({
+	droplet_installation_status: z.object({
+		generated_at: z.string(),
+		sections: z.object({
+			install_status: section(z.object({
+				status: z.string(),
+				delivery_state: z.string().nullable()
+			})),
+			lifecycle: section(z.object({ deliveries: z.array(z.looseObject({
+				event: z.string(),
+				trigger: z.string(),
+				state: z.string(),
+				attempts: z.number().int(),
+				last_status: z.union([z.number().int(), z.string()]).nullable(),
+				last_error_category: z.string().nullable().optional(),
+				created_at: z.string().optional(),
+				updated_at: z.string().optional()
+			})) })),
+			health: section(installationHealthSchema),
+			reconcile: section(z.object({
+				pinned_version: z.number().int().nullable(),
+				target_version: z.number().int().nullable(),
+				state: z.string(),
+				resources: z.array(reconcileResourceSchema),
+				truncated: z.boolean(),
+				grants: z.object({ count: z.number().int() }),
+				pending: z.object({ count: z.number().int() })
+			}))
+		})
+	}),
+	status: z.literal(200),
+	meta: z.object({
+		request_uuid: z.string().nullable(),
+		timestamp: z.string()
+	})
+});
+function createFluidInstallationClient({ installToken, baseUrl, fetch: fetcher = globalThis.fetch, timeoutMs = 1e4 }) {
+	let url;
+	try {
+		url = new URL(baseUrl);
+	} catch {
+		throw new TypeError("Invalid baseUrl");
+	}
+	if (url.username || url.password || url.search || url.hash || !(url.protocol === "https:" || url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname))) throw new TypeError("baseUrl must use HTTPS or local HTTP");
+	if (typeof installToken !== "string" || !installToken.trim()) throw new TypeError("installToken must be non-empty");
+	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new TypeError("timeoutMs must be positive");
+	const endpoint = `${url.toString().replace(/\/+$/, "")}/api/droplets/v2026-10/installation`;
+	return { async getInstallationStatus() {
+		const controller = new AbortController();
+		let timer;
+		const failure = (code, httpStatus) => ({
+			ok: false,
+			error: {
+				code,
+				message: `Installation status: ${code}`,
+				...httpStatus === void 0 ? {} : { httpStatus }
+			}
+		});
+		const read = async () => {
+			const response = await fetcher(endpoint, {
+				headers: { Authorization: `Bearer ${installToken}` },
+				signal: controller.signal,
+				cache: "no-store",
+				redirect: "error"
+			});
+			if (!response.ok) {
+				response.body?.cancel().catch(() => {});
+				return failure(response.status === 401 ? "unauthorized" : response.status === 403 ? "forbidden" : "http_error", response.status);
+			}
+			try {
+				return {
+					ok: true,
+					status: installationStatusSchema.parse(await response.json())
+				};
+			} catch {
+				return failure("invalid_response", response.status);
+			}
+		};
+		try {
+			return await Promise.race([read(), new Promise((resolve) => {
+				timer = setTimeout(() => {
+					resolve(failure("timeout"));
+					controller.abort();
+				}, timeoutMs);
+			})]);
+		} catch {
+			return failure("network");
+		} finally {
+			clearTimeout(timer);
+		}
+	} };
+}
+//#endregion
+export { createFluidInstallationClient, installationHealthSchema, installationStatusSchema, reconcileResourceSchema };

package/dist/next/reconcile.d.mts

@@ -0,0 +1,75 @@
+import { Logger } from "../redact.mjs";
+import { ReconcileResource } from "../installation.mjs";
+import { z } from "zod";
+
+//#region src/next/reconcile.d.ts
+declare const reconcileEventSchema: z.ZodType<ReconcileEvent>;
+type ReconcileEvent = {
+  event: "reconcile.succeeded" | "reconcile.failed" | "reconcile.awaiting_consent";
+  id: string;
+  occurred_at: string;
+  installation: {
+    uuid: string;
+    company_uuid: string;
+  };
+  attempt: number;
+  terminal: boolean;
+  resources?: ReconcileResource[];
+  resources_truncated?: true;
+  sandbox?: true;
+  from_version: string | null;
+  to_version: string | null;
+  pinned_version: string | null;
+};
+type ReconcileClaim = {
+  status: "claimed";
+  token: string;
+} | {
+  status: "in_flight";
+} | {
+  status: "done";
+};
+interface ReconcileAtomicDedupeStore {
+  /** Atomically reserves an id for the in-flight lease ttlMs, or reports its state. */
+  claim(id: string, ttlMs: number): Promise<ReconcileClaim> | ReconcileClaim;
+  /** Retains done for ttlMs only while the token owns an unexpired claim. */
+  complete(id: string, token: string, ttlMs: number): Promise<void> | void;
+  /** Frees only an unexpired claim still owned by the token. */
+  release(id: string, token: string): Promise<void> | void;
+}
+type ReconcileDedupeStore = ReconcileAtomicDedupeStore;
+interface ReconcileOptions {
+  secret: string;
+  logger?: Logger;
+  dedupe: ReconcileDedupeStore;
+  dedupeTtlMs?: number;
+  inFlightTtlMs?: number;
+  maxBodyBytes?: number;
+  name?: string;
+}
+type ReconcileHandler = (event: ReconcileEvent, ctx: {
+  headers: Headers;
+  signal: AbortSignal;
+}) => unknown | Promise<unknown>;
+/** Creates a bounded process-local event dedupe store. */
+declare function createInMemoryReconcileDedupe({
+  now,
+  maxEntries,
+  inFlightTtlMs
+}?: {
+  now?: () => number;
+  maxEntries?: number;
+  inFlightTtlMs?: number;
+}): ReconcileAtomicDedupeStore;
+/** Verifies and handles reconcile events, marking successful deliveries. */
+declare function withFluidReconcileEvents(handler: ReconcileHandler, {
+  secret,
+  logger,
+  dedupe,
+  dedupeTtlMs,
+  inFlightTtlMs,
+  maxBodyBytes,
+  name
+}: ReconcileOptions): (request: Request) => Promise<Response>;
+//#endregion
+export { ReconcileAtomicDedupeStore, ReconcileClaim, ReconcileDedupeStore, ReconcileEvent, ReconcileHandler, ReconcileOptions, createInMemoryReconcileDedupe, reconcileEventSchema, withFluidReconcileEvents };

package/dist/next/reconcile.mjs

@@ -0,0 +1,212 @@
+import { verifySignature } from "../signatures.mjs";
+import { consoleLogger } from "../redact.mjs";
+import { reconcileResourceSchema } from "../installation.mjs";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+//#region src/next/reconcile.ts
+const reconcileEventSchema = z.object({
+	event: z.enum([
+		"reconcile.succeeded",
+		"reconcile.failed",
+		"reconcile.awaiting_consent"
+	]),
+	id: z.string().regex(/^evt_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i),
+	occurred_at: z.iso.datetime({ offset: true }),
+	installation: z.object({
+		uuid: z.uuid(),
+		company_uuid: z.uuid()
+	}),
+	attempt: z.number().int().nonnegative(),
+	terminal: z.boolean(),
+	resources: z.array(reconcileResourceSchema).optional(),
+	resources_truncated: z.literal(true).optional(),
+	sandbox: z.literal(true).optional(),
+	from_version: z.string().nullable(),
+	to_version: z.string().nullable(),
+	pinned_version: z.string().nullable()
+});
+function createInMemoryReconcileDedupe({ now = Date.now, maxEntries = 1e4, inFlightTtlMs = 6e4 } = {}) {
+	if (!Number.isInteger(maxEntries) || maxEntries < 1) throw new TypeError("maxEntries must be positive");
+	if (!Number.isFinite(inFlightTtlMs) || inFlightTtlMs <= 0) throw new TypeError("inFlightTtlMs must be positive and finite");
+	const entries = new Map();
+	const prune = () => {
+		const time = now();
+		for (const [id, entry] of entries) if (entry.expiry <= time) entries.delete(id);
+	};
+	const mark = (id, ttlMs) => {
+		prune();
+		entries.delete(id);
+		while (entries.size >= maxEntries) entries.delete(entries.keys().next().value);
+		entries.set(id, {
+			status: "done",
+			expiry: now() + ttlMs
+		});
+	};
+	const owns = (id, token) => {
+		prune();
+		const entry = entries.get(id);
+		return entry?.status === "in_flight" && entry.token === token;
+	};
+	return {
+		claim(id, ttlMs) {
+			prune();
+			const entry = entries.get(id);
+			if (entry) return { status: entry.status };
+			while (entries.size >= maxEntries) entries.delete(entries.keys().next().value);
+			const token = randomUUID();
+			entries.set(id, {
+				status: "in_flight",
+				token,
+				expiry: now() + Math.min(ttlMs, inFlightTtlMs)
+			});
+			return {
+				status: "claimed",
+				token
+			};
+		},
+		complete(id, token, ttlMs) {
+			prune();
+			const entry = entries.get(id);
+			if (!entry || entry.status === "in_flight" && entry.token === token) mark(id, ttlMs);
+		},
+		release(id, token) {
+			if (owns(id, token)) entries.delete(id);
+		}
+	};
+}
+function withFluidReconcileEvents(handler, { secret, logger = consoleLogger, dedupe, dedupeTtlMs = 864e5, inFlightTtlMs = 6e4, maxBodyBytes = 1048576, name = "reconcile" }) {
+	if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 0) throw new TypeError("maxBodyBytes must be a nonnegative safe integer");
+	if (!Number.isFinite(inFlightTtlMs) || inFlightTtlMs <= 0) throw new TypeError("inFlightTtlMs must be positive and finite");
+	if (!Number.isFinite(dedupeTtlMs) || dedupeTtlMs <= 0) throw new TypeError("dedupeTtlMs must be positive and finite");
+	if (!dedupe || typeof dedupe.claim !== "function" || typeof dedupe.complete !== "function" || typeof dedupe.release !== "function") throw new TypeError("withFluidReconcileEvents requires an atomic dedupe store implementing claim, complete and release; pass createInMemoryReconcileDedupe() for a single instance or a shared store for multiple instances");
+	const store = dedupe;
+	const release = async (id, token) => {
+		try {
+			await store.release(id, token);
+		} catch {
+			logger.warn(`[fluid-webhook:${name}] dedupe release failed`, { id });
+		}
+	};
+	return async function POST(request) {
+		const invalid = () => Response.json({ error: "invalid request" }, { status: 400 });
+		let rawBody;
+		let rawBytes;
+		const tooLarge = () => {
+			logger.warn(`[fluid-webhook:${name}] rejected`, { reason: "payload too large" });
+			return Response.json({ error: "payload too large" }, { status: 413 });
+		};
+		const contentLength = request.headers.get("content-length");
+		if (contentLength !== null && Number(contentLength) > maxBodyBytes) {
+			request.body?.cancel().catch(() => {});
+			return tooLarge();
+		}
+		try {
+			const chunks = [];
+			let total = 0;
+			const reader = request.body?.getReader();
+			if (reader) try {
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					total += value.byteLength;
+					if (total > maxBodyBytes) {
+						reader.cancel().catch(() => {});
+						return tooLarge();
+					}
+					chunks.push(value);
+				}
+			} finally {
+				reader.releaseLock();
+			}
+			const bytes = new Uint8Array(total);
+			let offset = 0;
+			for (const chunk of chunks) {
+				bytes.set(chunk, offset);
+				offset += chunk.byteLength;
+			}
+			rawBytes = bytes;
+			rawBody = new TextDecoder().decode(bytes);
+		} catch {
+			return invalid();
+		}
+		const verified = verifySignature({
+			rawBody: rawBytes,
+			secret,
+			signature: request.headers.get("x-fluid-signature"),
+			timestamp: request.headers.get("x-fluid-timestamp")
+		});
+		if (!verified.valid) {
+			logger.warn(`[fluid-webhook:${name}] rejected`, { reason: verified.reason });
+			return Response.json({ error: "unauthorized" }, { status: 401 });
+		}
+		let body;
+		try {
+			body = JSON.parse(rawBody);
+		} catch {
+			return invalid();
+		}
+		if (typeof body === "object" && body !== null && "event" in body && typeof body.event === "string" && body.event.startsWith("reconcile.") && body.event !== "reconcile.succeeded" && body.event !== "reconcile.failed" && body.event !== "reconcile.awaiting_consent") {
+			logger.info(`[fluid-webhook:${name}] ignored`, { event: body.event });
+			return Response.json({
+				ok: true,
+				ignored: true
+			});
+		}
+		const parsed = reconcileEventSchema.safeParse(body);
+		if (!parsed.success) return invalid();
+		const event = parsed.data;
+		let token;
+		try {
+			const claim = await store.claim(event.id, Math.min(inFlightTtlMs, dedupeTtlMs));
+			if (claim.status === "in_flight") return Response.json({ error: "in flight" }, {
+				status: 503,
+				headers: { "retry-after": "30" }
+			});
+			if (claim.status === "done") return Response.json({
+				ok: true,
+				duplicate: true
+			});
+			token = claim.token;
+		} catch {
+			logger.warn(`[fluid-webhook:${name}] dedupe claim failed`, { id: event.id });
+			return Response.json({ error: "internal error" }, { status: 500 });
+		}
+		try {
+			if (event.event === "reconcile.failed") logger.error("reconcile.failed", {
+				id: event.id,
+				installation_uuid: event.installation.uuid,
+				attempt: event.attempt,
+				terminal: event.terminal,
+				error_codes: [...new Set((event.resources ?? []).flatMap((resource) => resource.error_code === null ? [] : [resource.error_code]))]
+			});
+			const result = await handler(event, {
+				headers: request.headers,
+				signal: request.signal
+			});
+			let response;
+			if (result instanceof Response) response = result;
+			else try {
+				response = Response.json(result ?? { ok: true });
+			} catch {
+				logger.warn(`[fluid-webhook:${name}] handler result not serializable`, { id: event.id });
+				response = Response.json({ ok: true });
+			}
+			if (response.ok) try {
+				await store.complete(event.id, token, dedupeTtlMs);
+			} catch {
+				logger.warn(`[fluid-webhook:${name}] dedupe complete failed`, { id: event.id });
+			}
+			else await release(event.id, token);
+			return response;
+		} catch (error) {
+			await release(event.id, token);
+			logger.error(`[fluid-webhook:${name}] handler threw`, {
+				id: event.id,
+				name: error instanceof Error ? error.name : "UnknownError"
+			});
+			return Response.json({ error: "internal error" }, { status: 500 });
+		}
+	};
+}
+//#endregion
+export { createInMemoryReconcileDedupe, reconcileEventSchema, withFluidReconcileEvents };

package/dist/next.d.mts

@@ -1,3 +1,4 @@
 import { CallbackContext, CallbackFailure, CallbackHandler, WithFluidCallbackConfig, withFluidCallback } from "./next/callbacks.mjs";
 import { INSTALL_EVENT, ResolvedWebhookPrincipal, WebhookContext, WebhookHandler, WebhookRoutingHints, WithFluidWebhookConfig, effectivePayload, withFluidWebhook } from "./next/webhooks.mjs";
-export { type CallbackContext, type CallbackFailure, type CallbackHandler, INSTALL_EVENT, type ResolvedWebhookPrincipal, type WebhookContext, type WebhookHandler, type WebhookRoutingHints, type WithFluidCallbackConfig, type WithFluidWebhookConfig, effectivePayload, withFluidCallback, withFluidWebhook };
+import { ReconcileAtomicDedupeStore, ReconcileClaim, ReconcileDedupeStore, ReconcileEvent, ReconcileHandler, ReconcileOptions, createInMemoryReconcileDedupe, reconcileEventSchema, withFluidReconcileEvents } from "./next/reconcile.mjs";
+export { type CallbackContext, type CallbackFailure, type CallbackHandler, INSTALL_EVENT, ReconcileAtomicDedupeStore, ReconcileClaim, ReconcileDedupeStore, ReconcileEvent, ReconcileHandler, ReconcileOptions, type ResolvedWebhookPrincipal, type WebhookContext, type WebhookHandler, type WebhookRoutingHints, type WithFluidCallbackConfig, type WithFluidWebhookConfig, createInMemoryReconcileDedupe, effectivePayload, reconcileEventSchema, withFluidCallback, withFluidReconcileEvents, withFluidWebhook };

package/dist/next.mjs

@@ -1,3 +1,4 @@
 import { withFluidCallback } from "./next/callbacks.mjs";
 import { INSTALL_EVENT, effectivePayload, withFluidWebhook } from "./next/webhooks.mjs";
-export { INSTALL_EVENT, effectivePayload, withFluidCallback, withFluidWebhook };
+import { createInMemoryReconcileDedupe, reconcileEventSchema, withFluidReconcileEvents } from "./next/reconcile.mjs";
+export { INSTALL_EVENT, createInMemoryReconcileDedupe, effectivePayload, reconcileEventSchema, withFluidCallback, withFluidReconcileEvents, withFluidWebhook };

package/dist/redact.mjs

@@ -21,7 +21,7 @@ function describeError(error) {
 	};
 }
 function scrubMessage(message) {
-	return message.replace(/[{[][\s\S]*[}\]]/g, "[STRUCTURED_CONTENT_REMOVED]").replace(/\b(?:cvt|wvt|dit|dri|drp|cbr)_[A-Za-z0-9._-]+/g, "[REDACTED]").replace(/\b(token|secret|password|credential|api[_-]?key|authorization|signature)\b\s*[:=]\s*\S+/gi, "$1=[REDACTED]");
+	return message.replace(/[{[][\s\S]*[}\]]/g, "[STRUCTURED_CONTENT_REMOVED]").replace(/\b(?:cvt|wvt|dit|dri|drp|cbr|dws)_[A-Za-z0-9._-]+/g, "[REDACTED]").replace(/\b(token|secret|password|credential|api[_-]?key|authorization|signature)\b\s*[:=]\s*\S+/gi, "$1=[REDACTED]");
 }
 function truncate(value, max) {
 	return value.length <= max ? value : `${value.slice(0, max)}…[truncated]`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/droplet-sdk",
-  "version": "0.2.70",
+  "version": "0.2.71",
   "description": "Signature verification and tenancy for Fluid droplet callbacks and webhooks",
   "type": "module",
   "license": "UNLICENSED",