experimental-a2 0.2.0 → 0.4.0

package/dist/platform-B4TnJtWu.js

@@ -0,0 +1,32 @@
+//#region src/platform.ts
+const SYMBOL_FOR_REQ_CONTEXT = Symbol.for("@vercel/request-context");
+function requestContext() {
+	try {
+		return Reflect.get(globalThis, SYMBOL_FOR_REQ_CONTEXT)?.get?.() ?? {};
+	} catch {
+		return {};
+	}
+}
+/** The current invocation's Vercel deployment identity, when available. */
+function platformVercelOidcToken() {
+	try {
+		const token = requestContext().headers?.["x-vercel-oidc-token"];
+		return typeof token === "string" && token.length > 0 ? token : null;
+	} catch {
+		return null;
+	}
+}
+function platformWaitUntil(promise) {
+	try {
+		requestContext().waitUntil?.(promise);
+	} catch {}
+}
+/** The invocation's termination time in epoch ms, or null if unknowable. */
+function invocationDeadlineMs() {
+	const deadline = requestContext().deadline;
+	if (deadline === void 0 || deadline === null) return null;
+	const ms = new Date(deadline).getTime();
+	return Number.isNaN(ms) ? null : ms;
+}
+//#endregion
+export { platformVercelOidcToken as n, platformWaitUntil as r, invocationDeadlineMs as t };

package/dist/react.d.ts

@@ -1,5 +1,5 @@
-import { a as EventDefs, c as Reducer, r as ContractEvent, t as AppendInput } from "./contract-C_3dIIEU.js";
-import { A2Client, Connection, PushResult } from "./client.js";
+import { a as EventDefs, c as PresencePatch, d as WithPresence, o as PresenceDefs, p as Reducer, r as ContractEvent, s as PresenceMap, t as AppendInput } from "./contract-jIfaR085.js";
+import { a as Connection, c as PushResult, t as A2Client } from "./client-BrfDXQ8A.js";
 import { ReactElement, ReactNode } from "react";
 //#region src/react.d.ts
 type SessionProviderProps<D extends EventDefs, S> = {
@@ -13,10 +13,33 @@ type SessionProviderProps<D extends EventDefs, S> = {
   initialIndex: number;
   /** Server-rendered event history through `initialIndex`. */
   initialEvents?: ContractEvent<D>[];
+  /**
+   * This client's presence identity — required to call `setPresence`.
+   * Caller-supplied (a user id, a tab nonce, a guest name): A2 does
+   * not invent an identity story.
+   */
+  participant?: string;
   children?: ReactNode;
 };
 type BoundSessionProviderProps<D extends EventDefs, S> = Omit<SessionProviderProps<D, S>, "api">;
-type UseSessionResult<D extends EventDefs, S> = {
+/**
+ * The presence members of the hook result — intersected in via
+ * `WithPresence`, so they exist exactly when the contract declares
+ * presence fields (the reducer is the client's typed handle on it).
+ */
+type UseSessionPresence<P extends PresenceDefs> = {
+  /** The replicated presence map, this client included (local echo). */
+  presence: PresenceMap<P>;
+  /**
+   * Fire-and-forget: validated locally, echoed into the map
+   * immediately, coalesced on the wire to a fixed cadence (a leading
+   * send immediately, then at most one merged send per interval;
+   * later values win per field), stamped with the frontier at send
+   * time as `seen`. Requires the provider's `participant`.
+   */
+  setPresence: (values: PresencePatch<P>["values"]) => void;
+};
+type UseSessionResult<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = WithPresence<P, UseSessionPresence<P>> & {
   /** The live view, folded through the shared reducer. */
   state: S;
   /** The raw observed feed `state` is folded from. */
@@ -36,19 +59,19 @@ type UseSessionResult<D extends EventDefs, S> = {
    */
   push: (...events: AppendInput<D>[]) => PushResult<D>;
 };
-type A2React<D extends EventDefs, S> = {
+type A2React<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = {
   SessionProvider: (props: SessionProviderProps<D, S>) => ReactElement;
-  useSession: () => UseSessionResult<D, S>;
+  useSession: () => UseSessionResult<D, S, P>;
 };
-type BoundA2React<D extends EventDefs, S> = {
+type BoundA2React<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = {
   SessionProvider: (props: BoundSessionProviderProps<D, S>) => ReactElement;
-  useSession: () => UseSessionResult<D, S>;
+  useSession: () => UseSessionResult<D, S, P>;
 };
-declare function createReact<D extends EventDefs, S>(options: {
-  client: A2Client<D, S>;
-}): BoundA2React<D, S>;
-declare function createReact<D extends EventDefs, S>(options: {
-  reducer: Reducer<D, S>;
-}): A2React<D, S>;
+declare function createReact<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>>(options: {
+  client: A2Client<D, S, P>;
+}): BoundA2React<D, S, P>;
+declare function createReact<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>>(options: {
+  reducer: Reducer<D, S, P>;
+}): A2React<D, S, P>;
 //#endregion
-export { A2React, BoundA2React, BoundSessionProviderProps, SessionProviderProps, UseSessionResult, createReact };
+export { A2React, BoundA2React, BoundSessionProviderProps, SessionProviderProps, UseSessionPresence, UseSessionResult, createReact };

package/dist/react.js

@@ -1,5 +1,5 @@
 "use client";
-import { createClient } from "./client.js";
+import { t as createClient } from "./client-Bt4tAKi9.js";
 import { createContext, createElement, useContext, useEffect, useMemo, useSyncExternalStore } from "react";
 //#region src/react.ts
 /**
@@ -17,13 +17,14 @@ import { createContext, createElement, useContext, useEffect, useMemo, useSyncEx
 function createReact(options) {
 	const Context = createContext(null);
 	const providerMounts = /* @__PURE__ */ new WeakMap();
-	const resolveSession = "client" in options ? (sessionId, _api, initialState, initialIndex, initialEvents) => options.client.session(sessionId, {
+	const resolveSession = "client" in options ? (sessionId, _api, initialState, initialIndex, initialEvents, participant) => options.client.session(sessionId, {
 		initialState,
 		initialIndex,
-		...initialEvents === void 0 ? {} : { initialEvents }
+		...initialEvents === void 0 ? {} : { initialEvents },
+		...participant === void 0 ? {} : { participant }
 	}) : (() => {
 		const clients = /* @__PURE__ */ new Map();
-		return (sessionId, api, initialState, initialIndex, initialEvents) => {
+		return (sessionId, api, initialState, initialIndex, initialEvents, participant) => {
 			if (api === void 0) throw new TypeError("SessionProvider requires api when createReact binds a reducer");
 			let client = clients.get(api);
 			if (!client) {
@@ -36,19 +37,21 @@ function createReact(options) {
 			return client.session(sessionId, {
 				initialState,
 				initialIndex,
-				...initialEvents === void 0 ? {} : { initialEvents }
+				...initialEvents === void 0 ? {} : { initialEvents },
+				...participant === void 0 ? {} : { participant }
 			});
 		};
 	})();
 	function SessionProvider(props) {
-		const { sessionId, initialState, initialIndex, initialEvents } = props;
+		const { sessionId, initialState, initialIndex, initialEvents, participant } = props;
 		const api = "api" in props ? props.api : void 0;
-		const client = useMemo(() => resolveSession(sessionId, api, initialState, initialIndex, initialEvents), [
+		const client = useMemo(() => resolveSession(sessionId, api, initialState, initialIndex, initialEvents, participant), [
 			sessionId,
 			api,
 			initialState,
 			initialIndex,
-			initialEvents
+			initialEvents,
+			participant
 		]);
 		useEffect(() => {
 			const mounts = providerMounts.get(client) ?? 0;
@@ -68,13 +71,21 @@ function createReact(options) {
 		const client = useContext(Context);
 		if (!client) throw new Error("useSession must be rendered inside its matching SessionProvider");
 		const snapshot = useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
-		return useMemo(() => ({
-			state: snapshot.state,
-			events: snapshot.events,
-			index: snapshot.index,
-			connection: snapshot.connection,
-			push: client.push
-		}), [snapshot, client]);
+		return useMemo(() => {
+			const { setPresence } = client;
+			const { presence } = snapshot;
+			return {
+				state: snapshot.state,
+				events: snapshot.events,
+				index: snapshot.index,
+				connection: snapshot.connection,
+				push: client.push,
+				...setPresence && presence ? {
+					presence,
+					setPresence
+				} : {}
+			};
+		}, [snapshot, client]);
 	}
 	return {
 		SessionProvider,

package/dist/scheduler-qstash.d.ts

@@ -0,0 +1,78 @@
+import { i as Clock } from "./store-C3sNAaBT.js";
+import { D as SchedulerTask, t as A2Scheduler } from "./server-YtPq7hjw.js";
+//#region src/scheduler-qstash.d.ts
+type QStashStoreOutage = {
+  version: 1;
+  /** Zero is the first successor created for a store outage. */
+  generation: number;
+  /** The first failing drain task's due time. Append identity lives on the task. */
+  rootDueAt?: number;
+};
+type QStashMessage = SchedulerTask & {
+  /** Provider-private state authenticated as part of QStash's signed body. */
+  _a2QStash?: QStashStoreOutage;
+};
+type QStashPublishRequest = {
+  url: string;
+  body: QStashMessage;
+  /** Headers the transport must deliver to the callback. */
+  headers?: Readonly<Record<string, string>>;
+  /** Header names the transport must redact from provider dashboard/API views. */
+  redact?: {
+    header: readonly string[];
+  };
+  /** Whole-second Unix timestamp. Omitted for an immediate delivery. */
+  notBefore?: number;
+  deduplicationId: string;
+  /** Delivery retries after the initial attempt. */
+  retries?: number;
+};
+/** The request shape passed to an injected `@upstash/qstash` client. */
+type QStashClientPublishRequest = Omit<QStashPublishRequest, "headers" | "redact"> & {
+  headers?: Record<string, string>;
+  redact?: {
+    header: string[];
+  };
+};
+/** The outbound part of `@upstash/qstash` used by the built-in transport. */
+type QStashPublishingClient = {
+  publishJSON(request: QStashClientPublishRequest): Promise<unknown>;
+};
+type QStashVerifyRequest = {
+  signature: string;
+  /** The untouched request body covered by the signature. */
+  body: string;
+  /** Exact destination URL, checked against the signature subject. */
+  url: string;
+  upstashRegion?: string;
+};
+/** The small part of `@upstash/qstash` this adapter needs. */
+type QStashTransport = {
+  publish(request: QStashPublishRequest): Promise<unknown>;
+  verify(request: QStashVerifyRequest): Promise<boolean>;
+};
+type QStashSchedulerOptions = {
+  /** Exact URL mounted with `schedulerHandler(...)`. Inferred in local dev and on Vercel. */
+  url?: string;
+  /** QStash API token. Default: `QSTASH_TOKEN`. */
+  token?: string;
+  /** QStash signing key. Default: `QSTASH_CURRENT_SIGNING_KEY`. */
+  currentSigningKey?: string;
+  /** Next QStash signing key. Default: `QSTASH_NEXT_SIGNING_KEY`. */
+  nextSigningKey?: string;
+  /** Delivery retries after the initial attempt. Default: provider default. */
+  retries?: number;
+  /** Maximum callback body and outbound task with outage headroom. Default 1 MiB. */
+  maxBodyBytes?: number;
+  /** Static callback headers. QStash receives them; A2 requests dashboard/API redaction. */
+  headers?: Readonly<Record<string, string>>;
+  /** Injectable publishing client. The built-in receiver still verifies callbacks. */
+  client?: QStashPublishingClient;
+  /** Injectable transport (tests). Default: `@upstash/qstash`. */
+  transport?: QStashTransport;
+  /** Injectable clock for due-time calculations (tests). */
+  clock?: Clock;
+};
+declare function qstash(options?: QStashSchedulerOptions): A2Scheduler;
+//#endregion
+export { QStashClientPublishRequest, QStashPublishRequest, QStashPublishingClient, QStashSchedulerOptions, QStashTransport, QStashVerifyRequest, qstash };