@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.3

package/dist/lib/server/crud/collection.d.ts

@@ -0,0 +1,164 @@
+/**
+ * vibesCrudCollection / vibesCrudItem — descriptor-driven CRUD endpoints.
+ *
+ * Combines `vibesGET`/`vibesPOST`/`vibesPATCH`/`vibesDELETE` middleware
+ * with the canonical `{ results }` / `{ result }` wire shape and the
+ * `storage/transform` runtime kind. The caller owns the DB query side
+ * (visibility filtering, table-specific shapes); the helper owns
+ * middleware wiring, response shape, and row↔descriptor mapping via
+ * the storage transform registered at the app level.
+ *
+ * ## Typing context.validated
+ *
+ * Each method's `fetch` / `insert` / `patch` / `remove` callback
+ * receives `(event, context)` where `context.validated.body|query|params`
+ * carries the parsed validation output. Because TypeScript cannot
+ * propagate generics through nested object properties at the call site
+ * (vibesGET's single-arg shape gets it for free; this helper's nested
+ * `list.validation` / `create.validation` shape does not), callbacks
+ * type-narrow with a local cast:
+ *
+ * ```ts
+ * insert: async (event, context) => {
+ *   const body = context.validated!.body as CreateModelBody;
+ *   ...
+ * }
+ * ```
+ *
+ * The cast is narrow and typed — untyped escape hatches are forbidden, but a
+ * `as <specific type>` narrowing on a value the route's `validation` schema
+ * already produced is the documented pattern.
+ *
+ * Usage:
+ *
+ * ```ts
+ * // apps/ai-web/src/routes/api/providers/+server.ts
+ * const { GET, POST } = vibesCrudCollection({
+ *   storageDescriptorId: 'ai.providers',
+ *   resolveTransform: (event, id) => resolveStorageTransform(event.locals.runtime, id),
+ *   list: {
+ *     ...quick.auth(),
+ *     fetch: async (event) => db.query.modelProviders.findMany({ where: visibilityFor(event) })
+ *   },
+ *   create: {
+ *     ...quick.auth(),
+ *     validation: { body: modelProviderCreateSchema },
+ *     insert: async (event, ctx, body) => db.insert(modelProviders).values(body).returning()
+ *   }
+ * });
+ *
+ * export { GET, POST };
+ * ```
+ *
+ * The helper resolves the `ai.providers` transform per request through the
+ * host-supplied `resolveTransform(event, descriptorId)` (typically
+ * `resolveStorageTransform(event.locals.runtime, id)`) and applies `fromRow`
+ * to every row returned to the client.
+ */
+import { type RequestEvent, type RequestHandler } from '@sveltejs/kit';
+import type { VibesConfig, VibesContext } from '../endpoint/types.js';
+import type { CrudListHooks, CrudGetHooks, CrudCreateHooks, CrudUpdateHooks, CrudDeleteHooks } from './index.js';
+import type { PaginatedData } from '../../pagination/schemas/common.ts';
+/**
+ * Structural storage transform. The owning storage package's transform
+ * implementation is assignable to this shape; kit imports no storage package.
+ */
+export interface StorageTransform<TRow = unknown, TDescriptor = unknown> {
+    /** Map a single row from the storage adapter into a wire-shape descriptor. */
+    fromRow(row: TRow): TDescriptor;
+    /** Map a wire-shape descriptor (or partial patch) into a storage row. Optional. */
+    toRow?(descriptor: Partial<TDescriptor>): Partial<TRow>;
+}
+/**
+ * Where a CRUD helper gets its transform. Exactly one of:
+ * - `resolveTransform(event, descriptorId)`: the host resolves the registered
+ *   transform from the request's runtime (`event.locals.runtime`). Returning
+ *   `null` explicitly means "no transform registered" (rows ARE the wire
+ *   shape); a throw propagates — resolution failures are never swallowed.
+ * - `transform`: a fixed transform (tests, static mappings).
+ */
+export type CrudTransformSource<TRow, TDescriptor> = {
+    transform: StorageTransform<TRow, TDescriptor>;
+    resolveTransform?: undefined;
+} | {
+    transform?: undefined;
+    resolveTransform: (event: RequestEvent, descriptorId: string) => Promise<StorageTransform<TRow, TDescriptor> | null>;
+};
+type MaybeAuth = Pick<VibesConfig, 'permissions' | 'metadata' | 'rateLimit' | 'caching'>;
+export interface VibesCrudCollectionListConfig<TRow, TValidation = unknown> extends MaybeAuth {
+    validation?: TValidation;
+    hooks?: CrudListHooks<TRow>;
+    /**
+     * Caller-supplied query that returns rows in the owning storage's
+     * native shape. Return a `PaginatedData<TRow>` to emit pagination metadata
+     * in response headers while preserving the canonical `{ results }` body.
+     * The helper maps each row through the registered `storage/transform`.
+     */
+    fetch: (event: RequestEvent, context: VibesContext<TValidation>) => Promise<TRow[] | PaginatedData<TRow>>;
+}
+export interface VibesCrudCollectionCreateConfig<TRow, TValidation = unknown> extends MaybeAuth {
+    validation: TValidation;
+    hooks?: CrudCreateHooks<TRow>;
+    /**
+     * Caller-supplied insert that returns the new row in storage shape.
+     * The helper maps through the transform before wrapping as
+     * `{ result }`.
+     */
+    insert: (event: RequestEvent, context: VibesContext<TValidation>) => Promise<TRow>;
+}
+export type VibesCrudCollectionOptions<TRow, TDescriptor, TListValidation = unknown, TCreateValidation = unknown> = CrudTransformSource<TRow, TDescriptor> & {
+    /** Storage manifest descriptor id, used to resolve the transform. */
+    storageDescriptorId: string;
+    list?: VibesCrudCollectionListConfig<TRow, TListValidation>;
+    create?: VibesCrudCollectionCreateConfig<TRow, TCreateValidation>;
+};
+export interface VibesCrudCollectionHandlers {
+    GET?: RequestHandler;
+    POST?: RequestHandler;
+}
+/**
+ * Build GET (list) + POST (create) handlers for a `/api/<resource>` route.
+ *
+ * Wire shape: `{ results: TDescriptor[] }` for GET, `{ result: TDescriptor }`
+ * for POST. The caller supplies `fetch` and `insert` callbacks; the helper
+ * wraps with `vibesGET` / `vibesPOST` and applies the descriptor's
+ * registered transform.
+ */
+export declare function vibesCrudCollection<TRow, TDescriptor = TRow, TListValidation = unknown, TCreateValidation = unknown>(options: VibesCrudCollectionOptions<TRow, TDescriptor, TListValidation, TCreateValidation>): VibesCrudCollectionHandlers;
+export interface VibesCrudItemGetConfig<TRow, TValidation = unknown> extends MaybeAuth {
+    validation?: TValidation;
+    hooks?: CrudGetHooks<TRow>;
+    /** Returns the row or `null` (helper sends 404 on null). */
+    fetch: (event: RequestEvent, context: VibesContext<TValidation>) => Promise<TRow | null>;
+    notFoundMessage?: string;
+}
+export interface VibesCrudItemUpdateConfig<TRow, TValidation = unknown> extends MaybeAuth {
+    validation: TValidation;
+    hooks?: CrudUpdateHooks<TRow>;
+    patch: (event: RequestEvent, context: VibesContext<TValidation>) => Promise<TRow>;
+}
+export interface VibesCrudItemDeleteConfig<TValidation = unknown> extends MaybeAuth {
+    validation?: TValidation;
+    hooks?: CrudDeleteHooks;
+    remove: (event: RequestEvent, context: VibesContext<TValidation>) => Promise<void>;
+}
+export type VibesCrudItemOptions<TRow, TDescriptor, TGetValidation = unknown, TUpdateValidation = unknown, TDeleteValidation = unknown> = CrudTransformSource<TRow, TDescriptor> & {
+    storageDescriptorId: string;
+    get?: VibesCrudItemGetConfig<TRow, TGetValidation>;
+    update?: VibesCrudItemUpdateConfig<TRow, TUpdateValidation>;
+    delete?: VibesCrudItemDeleteConfig<TDeleteValidation>;
+};
+export interface VibesCrudItemHandlers {
+    GET?: RequestHandler;
+    PATCH?: RequestHandler;
+    DELETE?: RequestHandler;
+}
+/**
+ * Build GET / PATCH / DELETE handlers for a `/api/<resource>/[id]` route.
+ *
+ * Wire shape: `{ result: TDescriptor }` for GET / PATCH, 204 no body for
+ * DELETE. Caller supplies `fetch`, `patch`, `remove` callbacks; helper
+ * wraps with vibes middleware and applies the registered transform.
+ */
+export declare function vibesCrudItem<TRow, TDescriptor = TRow, TGetValidation = unknown, TUpdateValidation = unknown, TDeleteValidation = unknown>(options: VibesCrudItemOptions<TRow, TDescriptor, TGetValidation, TUpdateValidation, TDeleteValidation>): VibesCrudItemHandlers;
+export {};

package/dist/lib/server/crud/collection.js

@@ -0,0 +1,227 @@
+/**
+ * vibesCrudCollection / vibesCrudItem — descriptor-driven CRUD endpoints.
+ *
+ * Combines `vibesGET`/`vibesPOST`/`vibesPATCH`/`vibesDELETE` middleware
+ * with the canonical `{ results }` / `{ result }` wire shape and the
+ * `storage/transform` runtime kind. The caller owns the DB query side
+ * (visibility filtering, table-specific shapes); the helper owns
+ * middleware wiring, response shape, and row↔descriptor mapping via
+ * the storage transform registered at the app level.
+ *
+ * ## Typing context.validated
+ *
+ * Each method's `fetch` / `insert` / `patch` / `remove` callback
+ * receives `(event, context)` where `context.validated.body|query|params`
+ * carries the parsed validation output. Because TypeScript cannot
+ * propagate generics through nested object properties at the call site
+ * (vibesGET's single-arg shape gets it for free; this helper's nested
+ * `list.validation` / `create.validation` shape does not), callbacks
+ * type-narrow with a local cast:
+ *
+ * ```ts
+ * insert: async (event, context) => {
+ *   const body = context.validated!.body as CreateModelBody;
+ *   ...
+ * }
+ * ```
+ *
+ * The cast is narrow and typed — untyped escape hatches are forbidden, but a
+ * `as <specific type>` narrowing on a value the route's `validation` schema
+ * already produced is the documented pattern.
+ *
+ * Usage:
+ *
+ * ```ts
+ * // apps/ai-web/src/routes/api/providers/+server.ts
+ * const { GET, POST } = vibesCrudCollection({
+ *   storageDescriptorId: 'ai.providers',
+ *   resolveTransform: (event, id) => resolveStorageTransform(event.locals.runtime, id),
+ *   list: {
+ *     ...quick.auth(),
+ *     fetch: async (event) => db.query.modelProviders.findMany({ where: visibilityFor(event) })
+ *   },
+ *   create: {
+ *     ...quick.auth(),
+ *     validation: { body: modelProviderCreateSchema },
+ *     insert: async (event, ctx, body) => db.insert(modelProviders).values(body).returning()
+ *   }
+ * });
+ *
+ * export { GET, POST };
+ * ```
+ *
+ * The helper resolves the `ai.providers` transform per request through the
+ * host-supplied `resolveTransform(event, descriptorId)` (typically
+ * `resolveStorageTransform(event.locals.runtime, id)`) and applies `fromRow`
+ * to every row returned to the client.
+ */
+import { error, json } from '@sveltejs/kit';
+import * as z from 'zod/v4';
+import { vibesGET, vibesPOST, vibesPATCH, vibesDELETE } from '../endpoint/wrapper.js';
+import { buildPaginationHeaders } from "../../pagination/server/index.js";
+async function pickTransform(source, storageDescriptorId, event) {
+    if (source.transform)
+        return source.transform;
+    const resolved = await source.resolveTransform(event, storageDescriptorId);
+    return resolved ?? { fromRow: identityRow };
+}
+/**
+ * The transform used when the host explicitly resolved "no transform
+ * registered": rows are already the wire shape.
+ */
+function identityRow(row) {
+    // SAFETY: a resolver returning `null` declares that this descriptor has no
+    // transform, so its rows ARE the wire shape and the caller's `TDescriptor`
+    // is `TRow` (the default of the helpers' `TDescriptor = TRow`). The
+    // intersection assertion states exactly that: the value is both.
+    return row;
+}
+/** One `validation` slot: a Zod schema (recognised by trait, so another Zod copy matches). */
+const validationSlot = z.custom((value) => value instanceof z.core.$ZodType);
+const validationSchema = z.object({
+    body: validationSlot.optional(),
+    query: validationSlot.optional(),
+    params: validationSlot.optional(),
+    headers: validationSlot.optional()
+});
+/**
+ * Project a CRUD method config down to a plain `VibesConfig`. The CRUD config
+ * carries extra fields (`fetch`/`insert`/`patch`/`remove`/`hooks`) the HTTP
+ * wrappers don't read; this keeps the object passed to `vibesGET`/… to exactly
+ * the `VibesConfig` surface. The caller's `validation` generic is unconstrained,
+ * so the slot is parsed here: every declared body/query/params/headers entry
+ * must be a Zod schema, otherwise building the route fails loudly rather than
+ * mis-validating requests later.
+ */
+function toVibesConfig(cfg) {
+    const validation = validationSchema.optional().safeParse(cfg.validation);
+    if (!validation.success) {
+        throw new TypeError(`CRUD validation must map body/query/params/headers to Zod schemas (${validation.error.issues
+            .map((issue) => issue.path.join('.') || 'validation')
+            .join(', ')})`);
+    }
+    return {
+        permissions: cfg.permissions,
+        metadata: cfg.metadata,
+        rateLimit: cfg.rateLimit,
+        caching: cfg.caching,
+        validation: validation.data
+    };
+}
+/**
+ * Present a handler typed for this config's own `validation` generic to the HTTP
+ * wrappers, which type `context.validated` from the config's `validation` slot.
+ */
+function forWrapper(handler) {
+    // SAFETY: `TValidation` is the type of the very `validation` object that
+    // `toVibesConfig` parsed and forwards to the wrapper, and the wrapper fills
+    // `context.validated` by parsing exactly those schemas before the handler
+    // runs, so the context it passes has the shape this handler was typed for.
+    // Generic erasure across the validation type parameter.
+    return handler;
+}
+/**
+ * Build GET (list) + POST (create) handlers for a `/api/<resource>` route.
+ *
+ * Wire shape: `{ results: TDescriptor[] }` for GET, `{ result: TDescriptor }`
+ * for POST. The caller supplies `fetch` and `insert` callbacks; the helper
+ * wraps with `vibesGET` / `vibesPOST` and applies the descriptor's
+ * registered transform.
+ */
+export function vibesCrudCollection(options) {
+    const handlers = {};
+    const getTransform = (event) => pickTransform(options, options.storageDescriptorId, event);
+    if (options.list) {
+        const listCfg = options.list;
+        const config = toVibesConfig(listCfg);
+        const inner = async (event, context) => {
+            if (listCfg.hooks?.onBeforeList)
+                await listCfg.hooks.onBeforeList(event, context);
+            const fetched = await listCfg.fetch(event, context);
+            const rows = Array.isArray(fetched) ? fetched : fetched.items;
+            const transform = await getTransform(event);
+            const results = rows.map((row) => transform.fromRow(row));
+            if (listCfg.hooks?.onAfterList)
+                await listCfg.hooks.onAfterList(event, context, rows);
+            if (!Array.isArray(fetched)) {
+                return json({ results }, { headers: buildPaginationHeaders(event.url, fetched.pagination) });
+            }
+            return { results };
+        };
+        handlers.GET = vibesGET(config, forWrapper(inner));
+    }
+    if (options.create) {
+        const createCfg = options.create;
+        const config = toVibesConfig(createCfg);
+        const inner = async (event, context) => {
+            if (createCfg.hooks?.onBeforeCreate)
+                await createCfg.hooks.onBeforeCreate(event, context);
+            const row = await createCfg.insert(event, context);
+            const transform = await getTransform(event);
+            const result = transform.fromRow(row);
+            if (createCfg.hooks?.onAfterCreate)
+                await createCfg.hooks.onAfterCreate(event, context, row);
+            return { result };
+        };
+        handlers.POST = vibesPOST(config, forWrapper(inner));
+    }
+    return handlers;
+}
+/**
+ * Build GET / PATCH / DELETE handlers for a `/api/<resource>/[id]` route.
+ *
+ * Wire shape: `{ result: TDescriptor }` for GET / PATCH, 204 no body for
+ * DELETE. Caller supplies `fetch`, `patch`, `remove` callbacks; helper
+ * wraps with vibes middleware and applies the registered transform.
+ */
+export function vibesCrudItem(options) {
+    const handlers = {};
+    const getTransform = (event) => pickTransform(options, options.storageDescriptorId, event);
+    if (options.get) {
+        const getCfg = options.get;
+        const config = toVibesConfig(getCfg);
+        const inner = async (event, context) => {
+            if (getCfg.hooks?.onBeforeGet)
+                await getCfg.hooks.onBeforeGet(event, context);
+            const row = await getCfg.fetch(event, context);
+            if (row === null || row === undefined) {
+                throw error(404, getCfg.notFoundMessage ?? getCfg.hooks?.notFoundMessage ?? 'Not found');
+            }
+            const transform = await getTransform(event);
+            const result = transform.fromRow(row);
+            if (getCfg.hooks?.onAfterGet)
+                await getCfg.hooks.onAfterGet(event, context, row);
+            return { result };
+        };
+        handlers.GET = vibesGET(config, forWrapper(inner));
+    }
+    if (options.update) {
+        const updateCfg = options.update;
+        const config = toVibesConfig(updateCfg);
+        const inner = async (event, context) => {
+            if (updateCfg.hooks?.onBeforeUpdate)
+                await updateCfg.hooks.onBeforeUpdate(event, context);
+            const row = await updateCfg.patch(event, context);
+            const transform = await getTransform(event);
+            const result = transform.fromRow(row);
+            if (updateCfg.hooks?.onAfterUpdate)
+                await updateCfg.hooks.onAfterUpdate(event, context, row);
+            return { result };
+        };
+        handlers.PATCH = vibesPATCH(config, forWrapper(inner));
+    }
+    if (options.delete) {
+        const deleteCfg = options.delete;
+        const config = toVibesConfig(deleteCfg);
+        const inner = async (event, context) => {
+            if (deleteCfg.hooks?.onBeforeDelete)
+                await deleteCfg.hooks.onBeforeDelete(event, context);
+            await deleteCfg.remove(event, context);
+            if (deleteCfg.hooks?.onAfterDelete)
+                await deleteCfg.hooks.onAfterDelete(event, context);
+            return new Response(null, { status: 204 });
+        };
+        handlers.DELETE = vibesDELETE(config, forWrapper(inner));
+    }
+    return handlers;
+}

package/dist/lib/server/crud/index.d.ts

@@ -0,0 +1,108 @@
+export * from './collection.js';
+/**
+ * vibeskit CRUD wire-shape helpers
+ *
+ * Standardizes the response body across every CRUD endpoint in the
+ * Vibes repositories so consumers (the cloud-api storage adapter, the
+ * datatable layer, app UIs) can treat any `/api/<resource>` endpoint
+ * the same way.
+ *
+ * Conventions:
+ *   - GET    /api/<resource>       → `{ results: T[] }`   (collection)
+ *   - POST   /api/<resource>       → `{ result: T }`      (created)
+ *   - GET    /api/<resource>/[id]  → `{ result: T }`      (one)
+ *   - PATCH  /api/<resource>/[id]  → `{ result: T }`      (updated)
+ *   - PUT    /api/<resource>/[id]  → `{ result: T }`      (replaced)
+ *   - DELETE /api/<resource>/[id]  → `204` no body        (deleted)
+ *
+ * No `status` field on the body — HTTP status codes carry that
+ * information. The body is exactly one of `{ results }` / `{ result }` /
+ * empty.
+ *
+ * ## Lifecycle hooks
+ *
+ * Each helper accepts an optional third `options` object with per-verb
+ * `onBefore<Verb>` / `onAfter<Verb>` hooks for side effects (audit logs,
+ * cache invalidation, webhooks, cascading constraint checks). Hooks fire
+ * AFTER auth/validation middleware has populated `context`, BEFORE the
+ * response is wrapped:
+ *
+ *   - `onBefore<Verb>` — runs before the user handler. Throwing from
+ *     here cancels the operation; the response uses whatever status
+ *     `error()` or the thrown value sets. Use for pre-condition checks.
+ *   - `onAfter<Verb>` — runs after the handler succeeds, receives the
+ *     handler's result. Side-effect only; return value is ignored. Use
+ *     for audit logging, cache invalidation, notification fan-out.
+ *
+ * Each helper wraps the matching `vibes*` method wrapper so all existing
+ * middleware (auth, rate-limit, cache, validation, OpenAPI registration,
+ * billing) carries over unchanged.
+ */
+import { type RequestHandler, type RequestEvent } from '@sveltejs/kit';
+import type { VibesConfig, VibesContext, VibesHandler } from '../endpoint/types.js';
+type BeforeHook = (event: RequestEvent, context: VibesContext) => Promise<void> | void;
+type AfterHook<T> = (event: RequestEvent, context: VibesContext, result: T) => Promise<void> | void;
+type AfterVoidHook = (event: RequestEvent, context: VibesContext) => Promise<void> | void;
+export interface CrudListHooks<T> {
+    onBeforeList?: BeforeHook;
+    onAfterList?: AfterHook<T[]>;
+}
+export interface CrudGetHooks<T> {
+    notFoundMessage?: string;
+    onBeforeGet?: BeforeHook;
+    onAfterGet?: AfterHook<T>;
+}
+export interface CrudCreateHooks<T> {
+    onBeforeCreate?: BeforeHook;
+    onAfterCreate?: AfterHook<T>;
+}
+export interface CrudUpdateHooks<T> {
+    onBeforeUpdate?: BeforeHook;
+    onAfterUpdate?: AfterHook<T>;
+}
+export interface CrudReplaceHooks<T> {
+    onBeforeReplace?: BeforeHook;
+    onAfterReplace?: AfterHook<T>;
+}
+export interface CrudDeleteHooks {
+    onBeforeDelete?: BeforeHook;
+    onAfterDelete?: AfterVoidHook;
+}
+/**
+ * GET /api/<resource> — list a collection.
+ *
+ * Handler returns `T[]`. Helper wraps as `{ results: T[] }`.
+ */
+export declare const vibesCrudList: <TConfig extends VibesConfig, T>(config: TConfig, handler: VibesHandler<T[], TConfig["validation"]>, hooks?: CrudListHooks<T>) => RequestHandler;
+/**
+ * GET /api/<resource>/[id] — fetch a single item.
+ *
+ * Handler returns `T | null`. Helper wraps non-null as `{ result: T }`;
+ * `null` → 404.
+ */
+export declare const vibesCrudGet: <TConfig extends VibesConfig, T>(config: TConfig, handler: VibesHandler<T | null, TConfig["validation"]>, hooks?: CrudGetHooks<T>) => RequestHandler;
+/**
+ * POST /api/<resource> — create one.
+ *
+ * Handler returns `T`. Helper wraps as `{ result: T }`.
+ */
+export declare const vibesCrudCreate: <TConfig extends VibesConfig, T>(config: TConfig, handler: VibesHandler<T, TConfig["validation"]>, hooks?: CrudCreateHooks<T>) => RequestHandler;
+/**
+ * PATCH /api/<resource>/[id] — update one (partial).
+ *
+ * Handler returns the updated `T`. Helper wraps as `{ result: T }`.
+ */
+export declare const vibesCrudUpdate: <TConfig extends VibesConfig, T>(config: TConfig, handler: VibesHandler<T, TConfig["validation"]>, hooks?: CrudUpdateHooks<T>) => RequestHandler;
+/**
+ * PUT /api/<resource>/[id] — replace one (full).
+ *
+ * Handler returns the replaced `T`. Helper wraps as `{ result: T }`.
+ */
+export declare const vibesCrudReplace: <TConfig extends VibesConfig, T>(config: TConfig, handler: VibesHandler<T, TConfig["validation"]>, hooks?: CrudReplaceHooks<T>) => RequestHandler;
+/**
+ * DELETE /api/<resource>/[id] — delete one.
+ *
+ * Handler does the deletion; helper returns 204 No Content with an empty
+ * body. Callers that need to confirm rely on the 204 + absence of 4xx/5xx.
+ */
+export declare const vibesCrudDelete: <TConfig extends VibesConfig>(config: TConfig, handler: VibesHandler<void, TConfig["validation"]>, hooks?: CrudDeleteHooks) => RequestHandler;

package/dist/lib/server/crud/index.js

@@ -0,0 +1,143 @@
+export * from './collection.js';
+/**
+ * vibeskit CRUD wire-shape helpers
+ *
+ * Standardizes the response body across every CRUD endpoint in the
+ * Vibes repositories so consumers (the cloud-api storage adapter, the
+ * datatable layer, app UIs) can treat any `/api/<resource>` endpoint
+ * the same way.
+ *
+ * Conventions:
+ *   - GET    /api/<resource>       → `{ results: T[] }`   (collection)
+ *   - POST   /api/<resource>       → `{ result: T }`      (created)
+ *   - GET    /api/<resource>/[id]  → `{ result: T }`      (one)
+ *   - PATCH  /api/<resource>/[id]  → `{ result: T }`      (updated)
+ *   - PUT    /api/<resource>/[id]  → `{ result: T }`      (replaced)
+ *   - DELETE /api/<resource>/[id]  → `204` no body        (deleted)
+ *
+ * No `status` field on the body — HTTP status codes carry that
+ * information. The body is exactly one of `{ results }` / `{ result }` /
+ * empty.
+ *
+ * ## Lifecycle hooks
+ *
+ * Each helper accepts an optional third `options` object with per-verb
+ * `onBefore<Verb>` / `onAfter<Verb>` hooks for side effects (audit logs,
+ * cache invalidation, webhooks, cascading constraint checks). Hooks fire
+ * AFTER auth/validation middleware has populated `context`, BEFORE the
+ * response is wrapped:
+ *
+ *   - `onBefore<Verb>` — runs before the user handler. Throwing from
+ *     here cancels the operation; the response uses whatever status
+ *     `error()` or the thrown value sets. Use for pre-condition checks.
+ *   - `onAfter<Verb>` — runs after the handler succeeds, receives the
+ *     handler's result. Side-effect only; return value is ignored. Use
+ *     for audit logging, cache invalidation, notification fan-out.
+ *
+ * Each helper wraps the matching `vibes*` method wrapper so all existing
+ * middleware (auth, rate-limit, cache, validation, OpenAPI registration,
+ * billing) carries over unchanged.
+ */
+import { error } from '@sveltejs/kit';
+import { vibesGET, vibesPOST, vibesPATCH, vibesPUT, vibesDELETE } from '../endpoint/wrapper.js';
+/**
+ * GET /api/<resource> — list a collection.
+ *
+ * Handler returns `T[]`. Helper wraps as `{ results: T[] }`.
+ */
+export const vibesCrudList = (config, handler, hooks) => {
+    const wrapped = async (event, context) => {
+        if (hooks?.onBeforeList)
+            await hooks.onBeforeList(event, context);
+        const results = await handler(event, context);
+        if (hooks?.onAfterList)
+            await hooks.onAfterList(event, context, results);
+        return { results };
+    };
+    return vibesGET(config, wrapped);
+};
+/**
+ * GET /api/<resource>/[id] — fetch a single item.
+ *
+ * Handler returns `T | null`. Helper wraps non-null as `{ result: T }`;
+ * `null` → 404.
+ */
+export const vibesCrudGet = (config, handler, hooks) => {
+    const wrapped = async (event, context) => {
+        if (hooks?.onBeforeGet)
+            await hooks.onBeforeGet(event, context);
+        const result = await handler(event, context);
+        if (result === null || result === undefined) {
+            throw error(404, hooks?.notFoundMessage ?? 'Not found');
+        }
+        if (hooks?.onAfterGet)
+            await hooks.onAfterGet(event, context, result);
+        return { result };
+    };
+    return vibesGET(config, wrapped);
+};
+/**
+ * POST /api/<resource> — create one.
+ *
+ * Handler returns `T`. Helper wraps as `{ result: T }`.
+ */
+export const vibesCrudCreate = (config, handler, hooks) => {
+    const wrapped = async (event, context) => {
+        if (hooks?.onBeforeCreate)
+            await hooks.onBeforeCreate(event, context);
+        const result = await handler(event, context);
+        if (hooks?.onAfterCreate)
+            await hooks.onAfterCreate(event, context, result);
+        return { result };
+    };
+    return vibesPOST(config, wrapped);
+};
+/**
+ * PATCH /api/<resource>/[id] — update one (partial).
+ *
+ * Handler returns the updated `T`. Helper wraps as `{ result: T }`.
+ */
+export const vibesCrudUpdate = (config, handler, hooks) => {
+    const wrapped = async (event, context) => {
+        if (hooks?.onBeforeUpdate)
+            await hooks.onBeforeUpdate(event, context);
+        const result = await handler(event, context);
+        if (hooks?.onAfterUpdate)
+            await hooks.onAfterUpdate(event, context, result);
+        return { result };
+    };
+    return vibesPATCH(config, wrapped);
+};
+/**
+ * PUT /api/<resource>/[id] — replace one (full).
+ *
+ * Handler returns the replaced `T`. Helper wraps as `{ result: T }`.
+ */
+export const vibesCrudReplace = (config, handler, hooks) => {
+    const wrapped = async (event, context) => {
+        if (hooks?.onBeforeReplace)
+            await hooks.onBeforeReplace(event, context);
+        const result = await handler(event, context);
+        if (hooks?.onAfterReplace)
+            await hooks.onAfterReplace(event, context, result);
+        return { result };
+    };
+    return vibesPUT(config, wrapped);
+};
+/**
+ * DELETE /api/<resource>/[id] — delete one.
+ *
+ * Handler does the deletion; helper returns 204 No Content with an empty
+ * body. Callers that need to confirm rely on the 204 + absence of 4xx/5xx.
+ */
+export const vibesCrudDelete = (config, handler, hooks) => {
+    const wrapped = async (event, context) => {
+        if (hooks?.onBeforeDelete)
+            await hooks.onBeforeDelete(event, context);
+        await handler(event, context);
+        if (hooks?.onAfterDelete)
+            await hooks.onAfterDelete(event, context);
+        return new Response(null, { status: 204 });
+    };
+    return vibesDELETE(config, wrapped);
+};

package/dist/lib/server/endpoint/iterable-response.d.ts

@@ -0,0 +1,2 @@
+/** Web-standard response transport; cancelling or failing a body releases its source. */
+export declare function createIterableResponse<T>(source: AsyncIterable<T>, encode: (value: T) => Uint8Array, init?: ResponseInit): Response;