@classytic/arc-next 0.9.1 → 0.11.0

package/README.md

@@ -8,6 +8,20 @@ React + TanStack Query SDK for the Arc backend framework. Typed CRUD hooks, opti
 npm install @classytic/arc-next
 ```
 
+## Type flow — use WIRE types for `T`
+
+`createCrudApi<T>`'s generic should be the kernel/module's exported **wire type**
+(plain JSON shape) — never a mongoose-flavored document type. Kernel → API →
+frontend then stays one type flow with zero casts:
+
+```ts
+import type { OrderWire } from '@classytic/order/wire'; // plain JSON shape
+const orders = createCrudApi<OrderWire>('orders');
+```
+
+Server-side counterpart: arc-* modules export their wire types per the
+module-publishing convention.
+
 ## Setup
 
 Call once at app init from a `"use client"` provider:

package/dist/api.d.ts

@@ -123,6 +123,50 @@ declare class BaseApi<TDoc = Record<string, unknown>, TCreate = Partial<TDoc>, T
     params?: QueryParams;
     options?: Omit<RequestOptions, 'token' | 'organizationId'>;
   }): Promise<PaginatedResult<TDoc>>;
+  /**
+   * Count records matching the filters — arc's list-route dispatch verb
+   * (`?_count=true`): same permissions/row-filters/tenant scoping as
+   * `getAll`, ZERO documents fetched. Cheapest way to answer "how many".
+   */
+  count({
+    token,
+    organizationId,
+    params,
+    options
+  }?: {
+    token?: string | null;
+    organizationId?: string | null;
+    params?: QueryParams;
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<number>;
+  /** Whether ANY record matches the filters (`?_exists=true`). */
+  exists({
+    token,
+    organizationId,
+    params,
+    options
+  }?: {
+    token?: string | null;
+    organizationId?: string | null;
+    params?: QueryParams;
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<boolean>;
+  /** Distinct values of a field across matching records (`?_distinct=field`). */
+  distinct<TValue = unknown>({
+    token,
+    organizationId,
+    field,
+    params,
+    options
+  }: {
+    token?: string | null;
+    organizationId?: string | null;
+    field: string;
+    params?: QueryParams;
+    options?: Omit<RequestOptions, 'token' | 'organizationId'>;
+  }): Promise<TValue[]>;
+  /** Shared raw GET against the list route (dispatch verbs bypass pagination parsing). */
+  private getAllRaw;
   getById({
     token,
     organizationId,

package/dist/api.js

@@ -105,6 +105,60 @@ var BaseApi = class {
 		if (organizationId) requestOptions.organizationId = organizationId;
 		return this.requestFn("GET", `${this.baseUrl}?${queryString}`, this.withHeaders(requestOptions));
 	}
+	/**
+	* Count records matching the filters — arc's list-route dispatch verb
+	* (`?_count=true`): same permissions/row-filters/tenant scoping as
+	* `getAll`, ZERO documents fetched. Cheapest way to answer "how many".
+	*/
+	async count({ token = null, organizationId = null, params = {}, options = {} } = {}) {
+		return extractVerbField(await this.getAllRaw({
+			token,
+			organizationId,
+			params: {
+				...params,
+				_count: true
+			},
+			options
+		}), "count");
+	}
+	/** Whether ANY record matches the filters (`?_exists=true`). */
+	async exists({ token = null, organizationId = null, params = {}, options = {} } = {}) {
+		return extractVerbField(await this.getAllRaw({
+			token,
+			organizationId,
+			params: {
+				...params,
+				_exists: true
+			},
+			options
+		}), "exists");
+	}
+	/** Distinct values of a field across matching records (`?_distinct=field`). */
+	async distinct({ token = null, organizationId = null, field, params = {}, options = {} }) {
+		if (!field) throw new Error("field is required");
+		return extractVerbField(await this.getAllRaw({
+			token,
+			organizationId,
+			params: {
+				...params,
+				_distinct: field
+			},
+			options
+		}), "values");
+	}
+	/** Shared raw GET against the list route (dispatch verbs bypass pagination parsing). */
+	async getAllRaw({ token = null, organizationId = null, params = {}, options = {} }) {
+		const mergedParams = {
+			...this.config.defaultParams,
+			...params
+		};
+		const processedParams = this.prepareParams(mergedParams);
+		const queryString = this.createQueryString(processedParams);
+		const requestOptions = { ...this.withCacheDefault(options) };
+		if (token) requestOptions.token = token;
+		if (organizationId) requestOptions.organizationId = organizationId;
+		return this.requestFn("GET", `${this.baseUrl}?${queryString}`, this.withHeaders(requestOptions));
+	}
 	async getById({ token = null, organizationId = null, id, params = {}, options = {} }) {
 		if (!id) throw new Error("ID is required");
 		const queryString = this.createQueryString(params);
@@ -255,6 +309,18 @@ function isKeysetPagination(response) {
 function isAggregatePagination(response) {
 	return "method" in response && response.method === "aggregate";
 }
+/**
+* Dispatch-verb responses are small objects (`{ count }`, `{ exists }`,
+* `{ values }`). Parse defensively across envelope variants (bare vs
+* `{ data: ... }`) so minor server envelope changes don't break clients.
+*/
+function extractVerbField(res, field) {
+	const r = res;
+	if (r && field in r) return r[field];
+	const d = r?.data ?? null;
+	if (d && field in d) return d[field];
+	throw new Error(`[arc-next] unexpected dispatch-verb response shape (missing '${field}')`);
+}
 
 //#endregion
 export { BaseApi, createCrudApi, isAggregatePagination, isKeysetPagination, isOffsetPagination };

package/dist/cache.d.ts

@@ -110,6 +110,20 @@ interface QueryKeys {
  * is identical between server (prefetch) and client (hooks), so RSC SSR
  * hydration matches what client-side `useList`/`useDetail` produce.
  */
+/**
+ * Org-normalized key params — the ONE way hooks AND prefetchers merge
+ * `organizationId` into a query-key params object.
+ *
+ * Why this exists: TanStack's key hash (`hashKey`) drops `undefined` object
+ * values but KEEPS `null` — so `{ organizationId: null }` and `{}` are
+ * DIFFERENT cache entries. Auth resolution returns `organizationId: null`
+ * for org-less callers (public storefronts), while server prefetchers
+ * conditionally omitted the field — producing keys that never matched and
+ * silently defeating SSR hydration (the client refetched everything).
+ * Normalizing here (omit when nullish) makes hook and prefetch keys equal
+ * by construction. Covered by tests/key-parity.test.ts.
+ */
+declare function withOrgParams(organizationId: string | null | undefined, params?: Record<string, unknown>): Record<string, unknown>;
 declare function createQueryKeys(entityKey: string): QueryKeys;
 interface CacheUtils<T> {
   invalidateAll: (client: QueryClient) => Promise<void>;
@@ -149,4 +163,4 @@ interface CacheUtils<T> {
  */
 declare function createCacheUtils<T>(KEYS: QueryKeys): CacheUtils<T>;
 //#endregion
-export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache };
+export { CacheUtils, DEFAULT_QUERY_CONFIG, PaginationData, QUERY_CONFIGS, QueryKeys, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache, withOrgParams };

package/dist/cache.js

@@ -221,6 +221,26 @@ function mergeItemIntoListPage(page, targetId, item, idField) {
 * is identical between server (prefetch) and client (hooks), so RSC SSR
 * hydration matches what client-side `useList`/`useDetail` produce.
 */
+/**
+* Org-normalized key params — the ONE way hooks AND prefetchers merge
+* `organizationId` into a query-key params object.
+*
+* Why this exists: TanStack's key hash (`hashKey`) drops `undefined` object
+* values but KEEPS `null` — so `{ organizationId: null }` and `{}` are
+* DIFFERENT cache entries. Auth resolution returns `organizationId: null`
+* for org-less callers (public storefronts), while server prefetchers
+* conditionally omitted the field — producing keys that never matched and
+* silently defeating SSR hydration (the client refetched everything).
+* Normalizing here (omit when nullish) makes hook and prefetch keys equal
+* by construction. Covered by tests/key-parity.test.ts.
+*/
+function withOrgParams(organizationId, params = {}) {
+	const { organizationId: _drop, ...rest } = params;
+	return organizationId ? {
+		organizationId,
+		...rest
+	} : rest;
+}
 function createQueryKeys(entityKey) {
 	return {
 		all: [entityKey],
@@ -300,4 +320,4 @@ function createCacheUtils(KEYS) {
 }
 
 //#endregion
-export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache };
+export { DEFAULT_QUERY_CONFIG, QUERY_CONFIGS, createCacheUtils, createQueryKeys, extractItem, extractItems, getItemId, normalizePagination, syncDetailToLists, updateListCache, withOrgParams };

package/dist/client.d.ts

@@ -141,6 +141,33 @@ declare function isAbortError(error: unknown): boolean;
  * if (isArcErrorCode(error, 'ORG_CONTEXT_REQUIRED')) promptOrgSelector();
  */
 declare function isArcErrorCode(error: unknown, code: ArcErrorCode): error is ArcApiError;
+/** `details` payload of arc's `quota.exceeded` 429 (`requireQuota`). */
+interface QuotaDetails {
+  /** The metered counter, e.g. `ai.tokens`, `export.runs`. */
+  kind: string;
+  used: number;
+  limit: number;
+  /** Billing period key, `YYYY-MM`. */
+  period: string;
+  /** ISO timestamp of the next period start — render "resets {date}". */
+  resetsAt: string;
+}
+/**
+ * Type guard for arc's quota denial (429 `quota.exceeded` from
+ * `requireQuota`). Render a meter, not a generic failure:
+ *
+ * @example
+ * if (isQuotaExceeded(err)) {
+ *   const q = getQuotaDetails(err);
+ *   toast(`${q.used.toLocaleString()} of ${q.limit.toLocaleString()} ${q.kind} used — resets ${new Date(q.resetsAt).toLocaleDateString()}`);
+ * }
+ *
+ * NEVER auto-retry these — a monthly quota doesn't reset between retries
+ * (the shared query client already refuses; see query-client.ts).
+ */
+declare function isQuotaExceeded(error: unknown): error is ArcApiError;
+/** Structured quota details from a `quota.exceeded` error (null when absent/malformed). */
+declare function getQuotaDetails(error: unknown): QuotaDetails | null;
 /**
  * Specific predicate for arc's bulk-preset + orgGuard safety code.
  *
@@ -623,7 +650,19 @@ interface NextFetchOptions {
 }
 interface ApiRequestOptions {
   body?: unknown;
+  /**
+   * Bearer token for this request. THREE-STATE contract:
+   * - **omitted / `undefined`** → inherit the global `configureAuth()` context
+   *   (auto-injected by `handleApiRequest`, per-client instances, and hooks)
+   * - **explicit `null`** → deliberately unauthenticated (public endpoint)
+   * - **string** → use exactly this token (wins over the global context)
+   */
   token?: string | null;
+  /**
+   * Tenant/org id sent as `x-organization-id`. Same three-state contract as
+   * `token`: `undefined` = inherit `configureAuth().getOrgId`, `null` = send
+   * no org header (platform-scope calls), string = exactly this org.
+   */
   organizationId?: string | null;
   /** Flattened Next `revalidate` (see `next`). `false` = cache indefinitely. */
   revalidate?: number | false;
@@ -864,4 +903,4 @@ declare const arc: {
   delete: <T = unknown>(path: string, opts?: ArcFetchOptions) => Promise<T>;
 };
 //#endregion
-export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, ArcFetchOptions, AuthConfig, AuthErrorContext, AuthErrorHandler, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, ClientEncryptionConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, NextFetchOptions, RetryConfig, StreamUrlProtocol, TextResponse, ToastHandler, UseRouterHook, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };
+export { AfterResponseContext, AfterResponseInterceptor, ApiRequestOptions, ArcApiError, ArcApiErrorOptions, ArcClient, ArcClientConfig, ArcErrorCode, ArcFetchOptions, AuthConfig, AuthErrorContext, AuthErrorHandler, BeforeRequestContext, BeforeRequestInterceptor, BlobResponse, ClientConfig, ClientEncryptionConfig, HttpMethod, KNOWN_ARC_ERROR_CODES, NextFetchOptions, QuotaDetails, RetryConfig, StreamUrlProtocol, TextResponse, ToastHandler, UseRouterHook, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isValidationError };

package/dist/client.js

@@ -201,6 +201,29 @@ function isArcErrorCode(error, code) {
 	return isArcApiError(error) && error.code === code;
 }
 /**
+* Type guard for arc's quota denial (429 `quota.exceeded` from
+* `requireQuota`). Render a meter, not a generic failure:
+*
+* @example
+* if (isQuotaExceeded(err)) {
+*   const q = getQuotaDetails(err);
+*   toast(`${q.used.toLocaleString()} of ${q.limit.toLocaleString()} ${q.kind} used — resets ${new Date(q.resetsAt).toLocaleDateString()}`);
+* }
+*
+* NEVER auto-retry these — a monthly quota doesn't reset between retries
+* (the shared query client already refuses; see query-client.ts).
+*/
+function isQuotaExceeded(error) {
+	return isArcApiError(error) && error.status === 429 && error.code === "quota.exceeded";
+}
+/** Structured quota details from a `quota.exceeded` error (null when absent/malformed). */
+function getQuotaDetails(error) {
+	if (!isQuotaExceeded(error)) return null;
+	const d = error.json?.details;
+	if (!d || typeof d.kind !== "string" || typeof d.limit !== "number") return null;
+	return d;
+}
+/**
 * Specific predicate for arc's bulk-preset + orgGuard safety code.
 *
 * Arc's bulk endpoints (`POST/PATCH/DELETE /:resource/bulk`) reject any call
@@ -877,6 +900,12 @@ async function executeAttempt(config, method, endpoint, options, attempt) {
 */
 async function handleApiRequest(method, endpoint, options = {}) {
 	if (!clientConfig) throw new Error("arc-next: Client not configured. Call configureClient({ baseUrl }) before making API requests.");
+	if (authConfig) {
+		const resolved = { ...options };
+		if (resolved.token === void 0) resolved.token = readToken(authConfig.getToken);
+		if (resolved.organizationId === void 0) resolved.organizationId = authConfig.getOrgId?.() ?? null;
+		return executeRequest(clientConfig, method, endpoint, resolved);
+	}
 	return executeRequest(clientConfig, method, endpoint, options);
 }
 /**
@@ -1110,4 +1139,4 @@ const arc = {
 };
 
 //#endregion
-export { ArcApiError, KNOWN_ARC_ERROR_CODES, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isValidationError };
+export { ArcApiError, KNOWN_ARC_ERROR_CODES, _getAuthErrorHandler, _isAuthRecoverable, _resetArcFetchClient, _resetAuthRecovery, _resetAuthWarnings, _resolveRefreshedToken, _runAuthRecovery, arc, arcAuthHeaders, arcFetch, buildStreamUrl, configureAuth, configureClient, createAuthAwareClient, createAuthRefreshHandler, createClient, createQueryString, getAuthContext, getAuthMode, getBaseUrl, getClientAuthContext, getQuotaDetails, handleApiRequest, hasGlobalStaticAuth, isAbortError, isArcApiError, isArcErrorCode, isAutoIdempotency, isDuplicateKeyError, isOrgContextRequiredError, isQuotaExceeded, isValidationError };

package/dist/field-encryption.d.ts

@@ -0,0 +1,86 @@
+//#region src/field-encryption.d.ts
+/**
+ * `@classytic/arc-next/field-encryption` — client decrypt for arc's
+ * FIELD-mode ALE (`@classytic/arc/encryption` with `mode: 'fields'`).
+ *
+ * Field-mode responses stay `application/json`; only the configured field
+ * VALUES arrive as authenticated `arc.v1` envelopes
+ * (`arc.v1.<b64url(kid)>.<b64url(iv)>.<b64url(ct)>.<b64url(tag)>`,
+ * AES-256-GCM). This helper parses and decrypts those envelopes with the
+ * shared symmetric key, via Web Crypto — zero dependencies, works in Node
+ * 22+, Bun, Deno, and React Native (with a Web Crypto polyfill).
+ *
+ * ── SECURITY: trusted runtimes ONLY ─────────────────────────────────────
+ * Field mode is SYMMETRIC — whoever holds the key can decrypt every
+ * envelope ever produced under it. That key belongs in a Node BFF, a
+ * server component, or a native app's secure storage. It must NEVER ship
+ * in a browser bundle: anything readable by browser JavaScript is readable
+ * by every visitor. For payloads a browser must decrypt, use the
+ * asymmetric JWE path (`@classytic/arc-next/encryption`) instead — that is
+ * exactly why this lives in its own subpath the web bundle never imports.
+ * ────────────────────────────────────────────────────────────────────────
+ *
+ * Fail-closed: unknown `kid`, tampered ciphertext, or a malformed
+ * `arc.v1.*` token throws — an encrypted field is never silently passed
+ * through as ciphertext or dropped.
+ *
+ * @example Node BFF / server component
+ * ```ts
+ * import { createFieldDecryption } from '@classytic/arc-next/field-encryption';
+ *
+ * const ale = createFieldDecryption({
+ *   // 32-byte AES-256 keys by kid — keep the previous kid during rotation.
+ *   keys: { 'k-2026-07': keyBytes },
+ * });
+ *
+ * configureClient({
+ *   baseUrl: env.ARC_URL,
+ *   afterResponse: async (ctx) => {
+ *     // arc stamps `x-encrypted: true` on field-mode responses — only
+ *     // those are scanned; every other response passes through untouched.
+ *     if (ctx.response.headers.get('x-encrypted') === 'true') {
+ *       ctx.body = await ale.decryptFieldsDeep(ctx.body);
+ *     }
+ *     return ctx;
+ *   },
+ * });
+ * ```
+ */
+/** Version prefix shared with `@classytic/arc/encryption`'s field cipher. */
+declare const FIELD_ENVELOPE_PREFIX = "arc.v1";
+/** Parsed `arc.v1` envelope — `kid` exposed for key resolution. */
+interface ParsedFieldEnvelope {
+  readonly kid: string;
+  readonly iv: Uint8Array;
+  readonly ciphertext: Uint8Array;
+  readonly tag: Uint8Array;
+}
+interface FieldDecryptionOptions {
+  /**
+   * 32-byte AES-256 keys indexed by `kid`. Keep 2–3 entries across a key
+   * rotation so envelopes minted under the previous `kid` still decrypt.
+   */
+  keys: Record<string, Uint8Array>;
+}
+interface FieldDecryption {
+  /** Decrypt one `arc.v1` envelope → plaintext string. Throws on tamper/unknown kid. */
+  decryptField(token: string): Promise<string>;
+  /**
+   * Walk a parsed JSON value and decrypt every `arc.v1.*` string in place
+   * (arrays and plain objects recursed; other types untouched). Returns the
+   * same reference for pipeline ergonomics.
+   */
+  decryptFieldsDeep<T>(data: T): Promise<T>;
+}
+/** Parse an `arc.v1` envelope, or `null` when the token isn't one. */
+declare function parseFieldEnvelope(token: string): ParsedFieldEnvelope | null;
+/** True when a value is a well-formed `arc.v1` envelope. */
+declare function isFieldEnvelope(value: unknown): value is string;
+/**
+ * Build the field-mode decryptor. Keys are validated eagerly (fail-fast at
+ * boot, not on the first sensitive response) and imported into Web Crypto
+ * once per `kid`, then cached.
+ */
+declare function createFieldDecryption(options: FieldDecryptionOptions): FieldDecryption;
+//#endregion
+export { FIELD_ENVELOPE_PREFIX, FieldDecryption, FieldDecryptionOptions, ParsedFieldEnvelope, createFieldDecryption, isFieldEnvelope, parseFieldEnvelope };

package/dist/field-encryption.js

@@ -0,0 +1,159 @@
+//#region src/field-encryption.ts
+/**
+* `@classytic/arc-next/field-encryption` — client decrypt for arc's
+* FIELD-mode ALE (`@classytic/arc/encryption` with `mode: 'fields'`).
+*
+* Field-mode responses stay `application/json`; only the configured field
+* VALUES arrive as authenticated `arc.v1` envelopes
+* (`arc.v1.<b64url(kid)>.<b64url(iv)>.<b64url(ct)>.<b64url(tag)>`,
+* AES-256-GCM). This helper parses and decrypts those envelopes with the
+* shared symmetric key, via Web Crypto — zero dependencies, works in Node
+* 22+, Bun, Deno, and React Native (with a Web Crypto polyfill).
+*
+* ── SECURITY: trusted runtimes ONLY ─────────────────────────────────────
+* Field mode is SYMMETRIC — whoever holds the key can decrypt every
+* envelope ever produced under it. That key belongs in a Node BFF, a
+* server component, or a native app's secure storage. It must NEVER ship
+* in a browser bundle: anything readable by browser JavaScript is readable
+* by every visitor. For payloads a browser must decrypt, use the
+* asymmetric JWE path (`@classytic/arc-next/encryption`) instead — that is
+* exactly why this lives in its own subpath the web bundle never imports.
+* ────────────────────────────────────────────────────────────────────────
+*
+* Fail-closed: unknown `kid`, tampered ciphertext, or a malformed
+* `arc.v1.*` token throws — an encrypted field is never silently passed
+* through as ciphertext or dropped.
+*
+* @example Node BFF / server component
+* ```ts
+* import { createFieldDecryption } from '@classytic/arc-next/field-encryption';
+*
+* const ale = createFieldDecryption({
+*   // 32-byte AES-256 keys by kid — keep the previous kid during rotation.
+*   keys: { 'k-2026-07': keyBytes },
+* });
+*
+* configureClient({
+*   baseUrl: env.ARC_URL,
+*   afterResponse: async (ctx) => {
+*     // arc stamps `x-encrypted: true` on field-mode responses — only
+*     // those are scanned; every other response passes through untouched.
+*     if (ctx.response.headers.get('x-encrypted') === 'true') {
+*       ctx.body = await ale.decryptFieldsDeep(ctx.body);
+*     }
+*     return ctx;
+*   },
+* });
+* ```
+*/
+/** Version prefix shared with `@classytic/arc/encryption`'s field cipher. */
+const FIELD_ENVELOPE_PREFIX = "arc.v1";
+const ENVELOPE_PARTS = 6;
+const KEY_BYTES = 32;
+const decoder = new TextDecoder();
+function b64urlToBytes(part) {
+	const b64 = part.replace(/-/g, "+").replace(/_/g, "/");
+	const padded = b64.padEnd(Math.ceil(b64.length / 4) * 4, "=");
+	const bin = atob(padded);
+	const out = new Uint8Array(bin.length);
+	for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+	return out;
+}
+/** Parse an `arc.v1` envelope, or `null` when the token isn't one. */
+function parseFieldEnvelope(token) {
+	if (typeof token !== "string") return null;
+	const parts = token.split(".");
+	if (parts.length !== ENVELOPE_PARTS) return null;
+	const [v0, v1, kidPart, ivPart, ctPart, tagPart] = parts;
+	if (`${v0}.${v1}` !== "arc.v1") return null;
+	if (!kidPart || !ivPart || !ctPart || !tagPart) return null;
+	try {
+		return {
+			kid: decoder.decode(b64urlToBytes(kidPart)),
+			iv: b64urlToBytes(ivPart),
+			ciphertext: b64urlToBytes(ctPart),
+			tag: b64urlToBytes(tagPart)
+		};
+	} catch {
+		return null;
+	}
+}
+/** True when a value LOOKS like an envelope (prefix match — cheap scan gate). */
+function hasEnvelopePrefix(value) {
+	return typeof value === "string" && value.startsWith(`${"arc.v1"}.`);
+}
+/** True when a value is a well-formed `arc.v1` envelope. */
+function isFieldEnvelope(value) {
+	return hasEnvelopePrefix(value) && parseFieldEnvelope(value) !== null;
+}
+/**
+* Build the field-mode decryptor. Keys are validated eagerly (fail-fast at
+* boot, not on the first sensitive response) and imported into Web Crypto
+* once per `kid`, then cached.
+*/
+function createFieldDecryption(options) {
+	const kids = Object.keys(options.keys);
+	if (kids.length === 0) throw new Error("[arc-next/field-encryption] at least one key is required.");
+	for (const kid of kids) {
+		const key = options.keys[kid];
+		if (!(key instanceof Uint8Array) || key.length !== KEY_BYTES) throw new Error(`[arc-next/field-encryption] key '${kid}' must be a ${KEY_BYTES}-byte Uint8Array (AES-256).`);
+	}
+	const imported = /* @__PURE__ */ new Map();
+	function keyFor(kid) {
+		let p = imported.get(kid);
+		if (!p) {
+			const raw = options.keys[kid];
+			if (!raw) throw new Error(`[arc-next/field-encryption] no key for kid '${kid}' — keep the previous kid configured during rotation so in-flight envelopes still decrypt.`);
+			p = crypto.subtle.importKey("raw", raw, { name: "AES-GCM" }, false, ["decrypt"]);
+			imported.set(kid, p);
+		}
+		return p;
+	}
+	async function decryptField(token) {
+		const envelope = parseFieldEnvelope(token);
+		if (!envelope) throw new Error("[arc-next/field-encryption] malformed arc.v1 envelope.");
+		const key = await keyFor(envelope.kid);
+		const combined = new Uint8Array(envelope.ciphertext.length + envelope.tag.length);
+		combined.set(envelope.ciphertext);
+		combined.set(envelope.tag, envelope.ciphertext.length);
+		try {
+			const plaintext = await crypto.subtle.decrypt({
+				name: "AES-GCM",
+				iv: envelope.iv
+			}, key, combined);
+			return decoder.decode(plaintext);
+		} catch {
+			throw new Error(`[arc-next/field-encryption] decryption failed for kid '${envelope.kid}' — tampered ciphertext or wrong key.`);
+		}
+	}
+	async function walk(node) {
+		if (Array.isArray(node)) {
+			for (let i = 0; i < node.length; i++) {
+				const value = node[i];
+				if (hasEnvelopePrefix(value)) node[i] = await decryptField(value);
+				else await walk(value);
+			}
+			return;
+		}
+		if (node !== null && typeof node === "object") {
+			const record = node;
+			for (const prop of Object.keys(record)) {
+				const value = record[prop];
+				if (hasEnvelopePrefix(value)) record[prop] = await decryptField(value);
+				else await walk(value);
+			}
+		}
+	}
+	async function decryptFieldsDeep(data) {
+		if (hasEnvelopePrefix(data)) return await decryptField(data);
+		await walk(data);
+		return data;
+	}
+	return {
+		decryptField,
+		decryptFieldsDeep
+	};
+}
+
+//#endregion
+export { FIELD_ENVELOPE_PREFIX, createFieldDecryption, isFieldEnvelope, parseFieldEnvelope };

package/dist/hooks.d.ts

@@ -21,7 +21,7 @@ import { QueryKey, UseQueryResult } from "@tanstack/react-query";
  * any cast — yet a vanilla `createCrudApi('todos')` instance has none of them
  * in autocomplete unless you opt in.
  */
-type CrudApi<T = unknown, TCreate = Partial<T>, TUpdate = Partial<T>> = Pick<BaseApi<T, TCreate, TUpdate>, 'getAll' | 'getById' | 'create' | 'update' | 'delete'> & {
+type CrudApi<T = unknown, TCreate = Partial<T>, TUpdate = Partial<T>> = Pick<BaseApi<T, TCreate, TUpdate>, 'getAll' | 'getById' | 'create' | 'update' | 'delete' | 'count'> & {
   upload?: BaseApi<T, TCreate, TUpdate>['upload'];
   dispatchAction?: BaseApi<T, TCreate, TUpdate>['dispatchAction'];
   invokeRoute?: BaseApi<T, TCreate, TUpdate>['invokeRoute']; /** Declared aggregations (arc 2.13+). Always available on BaseApi. */
@@ -89,6 +89,14 @@ interface CrudHooksConfig<T, TCreate = Partial<T>, TUpdate = Partial<T>> {
     gcTime?: number;
     refetchOnWindowFocus?: boolean;
     structuralSharing?: boolean;
+    /**
+     * Declare this resource's read endpoints PUBLIC (`allowPublic` on the
+     * server — e.g. a storefront catalog). Read hooks then enable token-less
+     * requests by default, so callers never have to pass `{ public: true }`
+     * per hook. Leave unset for auth-gated resources (cart, orders, account) —
+     * they keep the bearer token-gate. An explicit per-call `public` wins.
+     */
+    defaultPublic?: boolean;
     messages?: {
       createSuccess?: string;
       createError?: string;
@@ -199,6 +207,12 @@ interface CrudHooksReturn<T, TCreate, TUpdate> {
   useActions: () => CrudActions<T, TCreate, TUpdate>;
   useBulkActions: () => BulkActions<T, TCreate>;
   useDeleted: (params?: Record<string, unknown>, options?: ListQueryOptions<T>) => ListQueryResult<T>;
+  /** Count-only query via arc's `?_count=true` dispatch verb — zero documents fetched. */
+  useCount: (params?: Record<string, unknown>, options?: {
+    enabled?: boolean;
+    staleTime?: number;
+    gcTime?: number;
+  }) => UseQueryResult<number, Error>;
   useDetailBySlug: (slug: string | null, options?: DetailQueryOptions<T>) => DetailQueryResult<T>;
   useTree: (params?: Record<string, unknown>, options?: ListQueryOptions<T>) => ListQueryResult<T>;
   useChildren: (parentId: string | null, params?: Record<string, unknown>, options?: ListQueryOptions<T>) => ListQueryResult<T>;