@loynazkovacs/theitemapp-backend-sdk 0.2.0 → 0.3.0

package/README.md

@@ -75,11 +75,30 @@ if (!user) return reply401();
 
 | Export | Purpose |
 | --- | --- |
-| `CoreApiClient`, `CoreApiError` | Typed CRUD over `/api/dynamic` (+ file upload, decrypt, bulk-upsert, atomic upsert). |
+| `CoreApiClient`, `CoreApiError` | Typed CRUD over `/api/dynamic`: `list`/`get`/`findBy`/`count`/`create`/`bulkCreate`/`update`/`updateAsUser`/`delete`/`hardDeleteByFilter`/`upsert`/`upsertOn`/`bulkUpsert`/`uploadFile`/`downloadFile`/`decrypt`. |
+| `client.asUser(creds, opts?)` | Scoped client that acts AS an end user — forwards their `Authorization`/`Cookie` (optionally alongside the functional key). Full method surface. |
 | `startAppRegistration` | Registration retry loop, API-key rotation capture, heartbeat, deregister, signal handlers. |
-| `verifyUser`, `normalizeId`, `userInAnyGroup` | Framework-agnostic auth primitives. |
+| `verifyUser`, `normalizeId`, `userInAnyGroup`, `verifyJwtLocal` | Framework-agnostic auth primitives (+ offline HS256 verification). |
 | `createExpressAuthMiddleware`, `createFastifyAuthPreHandler` | Drop-in middleware/preHandler. |
 
+### Read/write controls
+
+- `get(c, id, { populate: false })` — keep x-ref fields as id strings (`?populate=0`).
+- `create`/`update`/`upsertOn`/`bulkCreate` take an optional `WriteOptions` (`{ skipWebhooks?, headers? }`) for per-call control.
+- `upsertOn(c, matchOn[], doc)` — composite-key atomic upsert returning `{ ok, created, doc }`.
+- `decrypt(c, id, { throwOnError: true })` — throw instead of returning `null`.
+
+### Acting as an end user
+
+```ts
+// forward the caller's session so core attributes the write to them:
+await coreApi.asUser({ authorization: req.headers.authorization, cookie: req.headers.cookie })
+  .create('notes', { text: 'hi' });
+
+// keep the functional key too (app identity + user session):
+await coreApi.asUser({ jwt }, { keepApiKey: true }).uploadFile(bytes, { filename, mimeType });
+```
+
 ## Not yet covered (roadmap)
 
 - `aggregate()` — core exposes pivot aggregation through the dynamic list route

package/dist/auth.d.ts

@@ -5,7 +5,8 @@
  * session cookie / `Authorization` header to core's `GET /api/auth/me`, which
  * is the single source of truth for identity and group membership. Every
  * backend reimplemented this proxy (`authMiddleware.ts` / `auth.ts`); this is
- * the canonical version plus thin Express and Fastify adapters.
+ * the canonical version plus thin Express and Fastify adapters, and an offline
+ * HS256 `verifyJwtLocal` for backends that hold core's JWT secret.
  */
 export type AuthUser = {
     _id: string;
@@ -78,5 +79,19 @@ export declare function createFastifyAuthPreHandler(coreUrl: string, options?: {
 } & VerifyOptions): (request: FastifyReqLike, reply: FastifyReplyLike) => Promise<void>;
 /** True if the user belongs to any of the given group ids. */
 export declare function userInAnyGroup(user: Pick<AuthUser, 'groupIds'>, groupIds: Iterable<string>): boolean;
+export type JwtPayload = Record<string, unknown> & {
+    sub?: string;
+    username?: string;
+    groupIds?: string[];
+    exp?: number;
+    iat?: number;
+};
+/**
+ * Verify an **HS256** JWT locally against a shared `secret` (no network call).
+ * Returns the decoded payload, or `null` if the token is malformed, the
+ * signature is invalid, the algorithm isn't HS256, or it has expired. The
+ * caller supplies the secret matching core's `JWT_SECRET`.
+ */
+export declare function verifyJwtLocal(token: string, secret: string): JwtPayload | null;
 export {};
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,WAAW,EAClB,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAsC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUlD;AASD,KAAK,cAAc,GAAG;IAAE,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAE/E,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAC;CACxD;AACD,KAAK,WAAW,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,aAAkB,IAGtC,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,KAAG,OAAO,CAAC,IAAI,CAAC,CAiB1F;AAED,UAAU,cAAe,SAAQ,cAAc;IAC7C,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AACD,UAAU,gBAAgB;IACxB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAC;CACxD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,aAAkB,IAGvC,SAAS,cAAc,EAAE,OAAO,gBAAgB,KAAG,OAAO,CAAC,IAAI,CAAC,CAgB/E;AAED,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAGpG"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,WAAW,EAClB,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAsC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUlD;AASD,KAAK,cAAc,GAAG;IAAE,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAE/E,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAC;CACxD;AACD,KAAK,WAAW,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,aAAkB,IAGtC,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,KAAG,OAAO,CAAC,IAAI,CAAC,CAiB1F;AAED,UAAU,cAAe,SAAQ,cAAc;IAC7C,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AACD,UAAU,gBAAgB;IACxB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAC;CACxD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,aAAkB,IAGvC,SAAS,cAAc,EAAE,OAAO,gBAAgB,KAAG,OAAO,CAAC,IAAI,CAAC,CAgB/E;AAED,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAGpG;AAUD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAyB/E"}

package/dist/auth.js

@@ -5,8 +5,10 @@
  * session cookie / `Authorization` header to core's `GET /api/auth/me`, which
  * is the single source of truth for identity and group membership. Every
  * backend reimplemented this proxy (`authMiddleware.ts` / `auth.ts`); this is
- * the canonical version plus thin Express and Fastify adapters.
+ * the canonical version plus thin Express and Fastify adapters, and an offline
+ * HS256 `verifyJwtLocal` for backends that hold core's JWT secret.
  */
+import { createHmac, timingSafeEqual } from 'node:crypto';
 /**
  * Verify a caller against core. Returns the `AuthUser` on success, or `null`
  * if no credentials were supplied or core rejected them. Throws only when core
@@ -121,3 +123,45 @@ export function userInAnyGroup(user, groupIds) {
     const set = groupIds instanceof Set ? groupIds : new Set(groupIds);
     return user.groupIds.some((id) => set.has(id));
 }
+/**
+ * Verify an **HS256** JWT locally against a shared `secret` (no network call).
+ * Returns the decoded payload, or `null` if the token is malformed, the
+ * signature is invalid, the algorithm isn't HS256, or it has expired. The
+ * caller supplies the secret matching core's `JWT_SECRET`.
+ */
+export function verifyJwtLocal(token, secret) {
+    if (!token || !secret)
+        return null;
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return null;
+    const [headerB64, payloadB64, sigB64] = parts;
+    let header;
+    let payload;
+    try {
+        header = JSON.parse(base64UrlDecode(headerB64));
+        payload = JSON.parse(base64UrlDecode(payloadB64));
+    }
+    catch {
+        return null;
+    }
+    if (header.alg !== 'HS256')
+        return null;
+    const expected = base64ToUrl(createHmac('sha256', secret).update(`${headerB64}.${payloadB64}`).digest('base64'));
+    const a = new TextEncoder().encode(expected);
+    const b = new TextEncoder().encode(sigB64);
+    if (a.length !== b.length || !timingSafeEqual(a, b))
+        return null;
+    if (typeof payload.exp === 'number' && Date.now() / 1000 >= payload.exp)
+        return null;
+    return payload;
+}
+function base64UrlDecode(s) {
+    const b64 = s.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(s.length / 4) * 4, '=');
+    const bin = atob(b64); // DOM lib: base64 → latin1 binary string
+    const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0));
+    return new TextDecoder().decode(bytes); // reinterpret as UTF-8
+}
+function base64ToUrl(b64) {
+    return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}

package/dist/core-api-client.d.ts

@@ -1,6 +1,6 @@
 /**
  * CoreApiClient — a thin, typed client over core's `/api/dynamic/<collection>`
- * CRUD surface (plus the file-upload and decrypt endpoints).
+ * CRUD surface (plus file upload/download and decrypt endpoints).
  *
  * Every app backend on the platform previously hand-rolled its own copy of
  * this class (`coreApiClient.ts`), each drifting in features and error
@@ -9,8 +9,8 @@
  * Auth: writes use the app's functional `x-api-key` (auto-provisioned by core
  * on registration — see `startAppRegistration`), and by default set
  * `x-theitemapp-skip-webhooks` so high-frequency system writes don't fan out
- * through the webhook pipeline. Use `updateAsUser` to attribute a write to an
- * end user via their JWT instead.
+ * through the webhook pipeline. To act as an end user (forwarding their
+ * session), use `asUser(...)` for a scoped client, or `updateAsUser`.
  */
 export declare class CoreApiError extends Error {
     readonly status: number;
@@ -28,6 +28,27 @@ export type CoreApiConfig = {
      */
     skipWebhooks?: boolean;
 };
+/** Per-call write controls (create/update/upsert/bulk). */
+export type WriteOptions = {
+    /** Override the client's skip-webhooks behaviour for this single call. */
+    skipWebhooks?: boolean;
+    /** Extra headers merged into this request (e.g. an end-user Authorization). */
+    headers?: Record<string, string>;
+};
+/** Read controls for `get`/`list`. */
+export type GetOptions = {
+    /** `false` appends `?populate=0` so x-ref fields stay as id strings. */
+    populate?: boolean;
+};
+/** Credentials to act as an end user (forwarded to core). */
+export type UserCredentials = {
+    /** Full `Authorization` header value (e.g. `Bearer <jwt>`). */
+    authorization?: string;
+    /** Raw `Cookie` header value (forwards the user's session cookie). */
+    cookie?: string;
+    /** Bare JWT — sent as `Authorization: Bearer <jwt>` if `authorization` is unset. */
+    jwt?: string;
+};
 export type BulkUpsertResult = {
     upsertedCount: number;
     modifiedCount: number;
@@ -36,6 +57,22 @@ export type BulkUpsertResult = {
         error: string;
     }>;
 };
+export type BulkCreateResult<T = Record<string, unknown>> = {
+    ok: boolean;
+    created: number;
+    failed: number;
+    results: Array<{
+        index: number;
+        ok: boolean;
+        doc?: T;
+        error?: string;
+    }>;
+};
+export type UpsertResult<T = Record<string, unknown>> = {
+    ok: boolean;
+    created: boolean;
+    doc: T;
+};
 export type UploadFileOptions = {
     filename: string;
     mimeType: string;
@@ -44,6 +81,11 @@ export type UploadFileOptions = {
     groupIds?: string[];
     title?: string;
 };
+export type DownloadedFile = {
+    data: Uint8Array;
+    contentType: string;
+    filename?: string;
+};
 export declare class CoreApiClient {
     private readonly baseUrl;
     private readonly skipWebhooks;
@@ -55,19 +97,40 @@ export declare class CoreApiClient {
     getApiKey(): string;
     /** Whether a non-empty API key is present — gate writes on this post-registration. */
     isReady(): boolean;
+    /**
+     * Return a client scoped to act AS an end user — forwards their
+     * `Authorization`/`Cookie` so core attributes reads/writes (and RBAC) to
+     * that human. By default the functional `x-api-key` is dropped (core treats
+     * an api-key match as the system actor, overriding the user identity). Pass
+     * `{ keepApiKey: true }` to send BOTH (some apps authorise with the user
+     * session while still proving the app's identity). The returned client has
+     * the full method surface (list/get/create/update/delete/upsert/uploadFile…).
+     */
+    asUser(creds: UserCredentials, opts?: {
+        keepApiKey?: boolean;
+    }): CoreApiClient;
     /** Headers minus `Content-Type` — for requests with no JSON body (DELETE) or multipart. */
     private headersWithoutContentType;
+    /** Build write headers with per-call skip-webhooks / extra-header overrides. */
+    private writeHeaders;
     /**
      * List documents. `query` maps to core's dynamic list params, e.g.
-     * `{ _l: '50', _s: '-createdAt', someField: 'x' }`. Defaults to `_l=500`.
+     * `{ _l: '50', _s: '-createdAt', populate: '0', someField: 'x' }`. Defaults
+     * to `_l=500`; override by passing your own `_l`.
      */
     list<T = Record<string, unknown>>(collection: string, query?: Record<string, string>): Promise<T[]>;
+    /**
+     * Count documents matching `filter` (field filters + optional `_f` advanced
+     * JSON) without fetching them — `GET /api/dynamic/:collection/count`.
+     */
+    count(collection: string, filter?: Record<string, string>): Promise<number>;
     /**
      * Fetch one document by id. Returns `null` for a genuine 404; throws
      * `CoreApiError` for transient failures (401/403/429/5xx) so callers can
-     * distinguish "doesn't exist" from "couldn't read it".
+     * distinguish "doesn't exist" from "couldn't read it". Pass
+     * `{ populate: false }` to keep x-ref fields as id strings (`?populate=0`).
      */
-    get<T = Record<string, unknown>>(collection: string, id: string): Promise<T | null>;
+    get<T = Record<string, unknown>>(collection: string, id: string, opts?: GetOptions): Promise<T | null>;
     /**
      * Find a single document by an indexed field. Returns `null` for no match;
      * throws `CoreApiError` on transient failure (never masks a read error as
@@ -75,27 +138,47 @@ export declare class CoreApiClient {
      */
     findBy<T = Record<string, unknown>>(collection: string, field: string, value: string): Promise<T | null>;
     /** Create a document. Throws `CoreApiError` on failure. */
-    create<T = Record<string, unknown>>(collection: string, body: Record<string, unknown>): Promise<T>;
+    create<T = Record<string, unknown>>(collection: string, body: Record<string, unknown>, opts?: WriteOptions): Promise<T>;
+    /**
+     * Create up to 500 documents in one call — `POST /api/dynamic/:collection/bulk`.
+     * Returns core's `{ ok, created, failed, results }` (per-doc success/error).
+     */
+    bulkCreate<T = Record<string, unknown>>(collection: string, documents: Record<string, unknown>[], opts?: WriteOptions): Promise<BulkCreateResult<T>>;
     /** Update a document by id (PUT). Throws `CoreApiError` on failure. */
-    update<T = Record<string, unknown>>(collection: string, id: string, body: Record<string, unknown>): Promise<T>;
+    update<T = Record<string, unknown>>(collection: string, id: string, body: Record<string, unknown>, opts?: WriteOptions): Promise<T>;
     /**
      * Update a document AS the given user, by sending their short-lived JWT
      * (`Authorization: Bearer`) instead of the functional `x-api-key`. Core then
      * attributes the change to that human in the audit log and
-     * `_meta.lastModifiedByUserId`. The functional key is deliberately omitted —
-     * core treats an `x-api-key` match as the system actor, which would override
-     * the asserted user identity.
+     * `_meta.lastModifiedByUserId`. For richer user-scoped flows (cookie
+     * forwarding, multipart upload, reads) prefer `asUser(...)`.
      */
     updateAsUser<T = Record<string, unknown>>(collection: string, id: string, body: Record<string, unknown>, userJwt: string): Promise<T>;
     /** Soft-delete a document by id. Returns `true` on success or 404 (already gone). */
     delete(collection: string, id: string): Promise<boolean>;
     /**
-     * Atomically upsert a document by a unique field, via core's server-side
-     * `POST /api/dynamic/:collection/upsert` (single Mongo `findOneAndUpdate`).
-     * Falls back to a findBy + update/create pair on older cores that 404 the
-     * upsert route.
+     * Permanently delete documents matching `query` —
+     * `POST /api/dynamic/:collection/hard-delete-by-filter`. API-key auth only
+     * (system operation); the query must be non-empty. Returns `{ ok, deletedCount }`.
+     */
+    hardDeleteByFilter(collection: string, query: Record<string, unknown>): Promise<{
+        ok: boolean;
+        deletedCount: number;
+    }>;
+    /**
+     * Atomically upsert a document by a single unique field, via core's
+     * server-side `POST /api/dynamic/:collection/upsert`. Returns the document
+     * (or `null`). Falls back to findBy + update/create on older cores that 404
+     * the upsert route. For composite keys / the full `{ ok, created }` result,
+     * use `upsertOn`.
      */
     upsert<T = Record<string, unknown>>(collection: string, matchField: string, matchValue: string, body: Record<string, unknown>): Promise<T | null>;
+    /**
+     * Atomically upsert by a COMPOSITE match key — `POST .../upsert` with
+     * `{ matchOn, document }`. Returns the full `{ ok, created, doc }` result so
+     * callers can branch on whether a row was created vs updated.
+     */
+    upsertOn<T = Record<string, unknown>>(collection: string, matchOn: string[], document: Record<string, unknown>, opts?: WriteOptions): Promise<UpsertResult<T>>;
     private upsertLegacy;
     /**
      * Bulk-upsert up to 500 documents, matched by a composite key (typically
@@ -107,15 +190,26 @@ export declare class CoreApiClient {
      * Upload a file to core's file API (`POST /api/files/uploadDirect`). Returns
      * the created file document (`{ _id, originalName }`) for referencing.
      * Accepts a `Uint8Array` (a Node `Buffer` is a `Uint8Array`, so it works too).
+     * To upload AS an end user, call `asUser(creds).uploadFile(...)`.
      */
     uploadFile(data: Uint8Array, opts: UploadFileOptions): Promise<{
         _id: string;
         originalName: string;
     }>;
+    /**
+     * Download a file's bytes — `GET /api/files/:id/content`. Returns the bytes
+     * plus content-type/filename, or `null` on 404. To download AS an end user,
+     * call `asUser(creds).downloadFile(...)`.
+     */
+    downloadFile(fileId: string): Promise<DownloadedFile | null>;
     /**
      * Decrypt `x-encrypted` fields for a record via core's internal decrypt
-     * endpoint. Returns a map of field name → plaintext, or `null` on failure.
+     * endpoint. Returns a map of field name → plaintext. By default returns
+     * `null` on failure; pass `{ throwOnError: true }` to throw `CoreApiError`
+     * instead. To decrypt AS an end user, call `asUser(creds).decrypt(...)`.
      */
-    decrypt(collection: string, id: string): Promise<Record<string, string | null> | null>;
+    decrypt(collection: string, id: string, opts?: {
+        throwOnError?: boolean;
+    }): Promise<Record<string, string | null> | null>;
 }
 //# sourceMappingURL=core-api-client.d.ts.map

package/dist/core-api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core-api-client.d.ts","sourceRoot":"","sources":["../src/core-api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"core-api-client.d.ts","sourceRoot":"","sources":["../src/core-api-client.ts"],"names":[],"mappings":"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"}

package/dist/core-api-client.js

@@ -1,6 +1,6 @@
 /**
  * CoreApiClient — a thin, typed client over core's `/api/dynamic/<collection>`
- * CRUD surface (plus the file-upload and decrypt endpoints).
+ * CRUD surface (plus file upload/download and decrypt endpoints).
  *
  * Every app backend on the platform previously hand-rolled its own copy of
  * this class (`coreApiClient.ts`), each drifting in features and error
@@ -9,8 +9,8 @@
  * Auth: writes use the app's functional `x-api-key` (auto-provisioned by core
  * on registration — see `startAppRegistration`), and by default set
  * `x-theitemapp-skip-webhooks` so high-frequency system writes don't fan out
- * through the webhook pipeline. Use `updateAsUser` to attribute a write to an
- * end user via their JWT instead.
+ * through the webhook pipeline. To act as an end user (forwarding their
+ * session), use `asUser(...)` for a scoped client, or `updateAsUser`.
  */
 export class CoreApiError extends Error {
     status;
@@ -47,14 +47,49 @@ export class CoreApiClient {
     isReady() {
         return (this.headers['x-api-key']?.length ?? 0) > 0;
     }
+    /**
+     * Return a client scoped to act AS an end user — forwards their
+     * `Authorization`/`Cookie` so core attributes reads/writes (and RBAC) to
+     * that human. By default the functional `x-api-key` is dropped (core treats
+     * an api-key match as the system actor, overriding the user identity). Pass
+     * `{ keepApiKey: true }` to send BOTH (some apps authorise with the user
+     * session while still proving the app's identity). The returned client has
+     * the full method surface (list/get/create/update/delete/upsert/uploadFile…).
+     */
+    asUser(creds, opts = {}) {
+        const scoped = new CoreApiClient({
+            baseUrl: this.baseUrl,
+            apiKey: opts.keepApiKey ? (this.headers['x-api-key'] ?? null) : null,
+            skipWebhooks: this.skipWebhooks,
+        });
+        if (creds.authorization)
+            scoped.headers['Authorization'] = creds.authorization;
+        else if (creds.jwt)
+            scoped.headers['Authorization'] = `Bearer ${creds.jwt}`;
+        if (creds.cookie)
+            scoped.headers['Cookie'] = creds.cookie;
+        return scoped;
+    }
     /** Headers minus `Content-Type` — for requests with no JSON body (DELETE) or multipart. */
     headersWithoutContentType() {
         const { 'Content-Type': _ct, ...rest } = this.headers;
         return rest;
     }
+    /** Build write headers with per-call skip-webhooks / extra-header overrides. */
+    writeHeaders(opts) {
+        const h = { ...this.headers };
+        if (opts?.skipWebhooks === false)
+            delete h['x-theitemapp-skip-webhooks'];
+        else if (opts?.skipWebhooks === true)
+            h['x-theitemapp-skip-webhooks'] = '1';
+        if (opts?.headers)
+            Object.assign(h, opts.headers);
+        return h;
+    }
     /**
      * List documents. `query` maps to core's dynamic list params, e.g.
-     * `{ _l: '50', _s: '-createdAt', someField: 'x' }`. Defaults to `_l=500`.
+     * `{ _l: '50', _s: '-createdAt', populate: '0', someField: 'x' }`. Defaults
+     * to `_l=500`; override by passing your own `_l`.
      */
     async list(collection, query) {
         const params = new URLSearchParams({ _l: '500', ...query });
@@ -65,13 +100,28 @@ export class CoreApiClient {
         const data = await res.json();
         return Array.isArray(data) ? data : [];
     }
+    /**
+     * Count documents matching `filter` (field filters + optional `_f` advanced
+     * JSON) without fetching them — `GET /api/dynamic/:collection/count`.
+     */
+    async count(collection, filter) {
+        const qs = new URLSearchParams({ ...filter }).toString();
+        const url = `${this.baseUrl}/api/dynamic/${collection}/count${qs ? `?${qs}` : ''}`;
+        const res = await fetch(url, { headers: this.headers });
+        if (!res.ok)
+            throw new CoreApiError('COUNT', collection, res.status, await safeText(res));
+        const data = (await res.json());
+        return typeof data === 'number' ? data : Number(data?.count ?? 0);
+    }
     /**
      * Fetch one document by id. Returns `null` for a genuine 404; throws
      * `CoreApiError` for transient failures (401/403/429/5xx) so callers can
-     * distinguish "doesn't exist" from "couldn't read it".
+     * distinguish "doesn't exist" from "couldn't read it". Pass
+     * `{ populate: false }` to keep x-ref fields as id strings (`?populate=0`).
      */
-    async get(collection, id) {
-        const url = `${this.baseUrl}/api/dynamic/${collection}/${encodeURIComponent(id)}`;
+    async get(collection, id, opts) {
+        const qs = opts?.populate === false ? '?populate=0' : '';
+        const url = `${this.baseUrl}/api/dynamic/${collection}/${encodeURIComponent(id)}${qs}`;
         const res = await fetch(url, { headers: this.headers });
         if (res.ok)
             return (await res.json());
@@ -94,17 +144,30 @@ export class CoreApiClient {
         return Array.isArray(data) ? (data[0] ?? null) : null;
     }
     /** Create a document. Throws `CoreApiError` on failure. */
-    async create(collection, body) {
+    async create(collection, body, opts) {
         const url = `${this.baseUrl}/api/dynamic/${collection}`;
-        const res = await fetch(url, { method: 'POST', headers: this.headers, body: JSON.stringify(body) });
+        const res = await fetch(url, { method: 'POST', headers: this.writeHeaders(opts), body: JSON.stringify(body) });
         if (!res.ok)
             throw new CoreApiError('CREATE', collection, res.status, await safeText(res));
         return (await res.json());
     }
+    /**
+     * Create up to 500 documents in one call — `POST /api/dynamic/:collection/bulk`.
+     * Returns core's `{ ok, created, failed, results }` (per-doc success/error).
+     */
+    async bulkCreate(collection, documents, opts) {
+        if (documents.length === 0)
+            return { ok: true, created: 0, failed: 0, results: [] };
+        const url = `${this.baseUrl}/api/dynamic/${collection}/bulk`;
+        const res = await fetch(url, { method: 'POST', headers: this.writeHeaders(opts), body: JSON.stringify({ documents }) });
+        if (!res.ok)
+            throw new CoreApiError('BULK_CREATE', collection, res.status, await safeText(res));
+        return (await res.json());
+    }
     /** Update a document by id (PUT). Throws `CoreApiError` on failure. */
-    async update(collection, id, body) {
+    async update(collection, id, body, opts) {
         const url = `${this.baseUrl}/api/dynamic/${collection}/${encodeURIComponent(id)}`;
-        const res = await fetch(url, { method: 'PUT', headers: this.headers, body: JSON.stringify(body) });
+        const res = await fetch(url, { method: 'PUT', headers: this.writeHeaders(opts), body: JSON.stringify(body) });
         if (!res.ok)
             throw new CoreApiError('UPDATE', `${collection}/${id}`, res.status, await safeText(res));
         return (await res.json());
@@ -113,9 +176,8 @@ export class CoreApiClient {
      * Update a document AS the given user, by sending their short-lived JWT
      * (`Authorization: Bearer`) instead of the functional `x-api-key`. Core then
      * attributes the change to that human in the audit log and
-     * `_meta.lastModifiedByUserId`. The functional key is deliberately omitted —
-     * core treats an `x-api-key` match as the system actor, which would override
-     * the asserted user identity.
+     * `_meta.lastModifiedByUserId`. For richer user-scoped flows (cookie
+     * forwarding, multipart upload, reads) prefer `asUser(...)`.
      */
     async updateAsUser(collection, id, body, userJwt) {
         const url = `${this.baseUrl}/api/dynamic/${collection}/${encodeURIComponent(id)}`;
@@ -144,10 +206,26 @@ export class CoreApiClient {
         throw new CoreApiError('DELETE', `${collection}/${id}`, res.status, await safeText(res));
     }
     /**
-     * Atomically upsert a document by a unique field, via core's server-side
-     * `POST /api/dynamic/:collection/upsert` (single Mongo `findOneAndUpdate`).
-     * Falls back to a findBy + update/create pair on older cores that 404 the
-     * upsert route.
+     * Permanently delete documents matching `query` —
+     * `POST /api/dynamic/:collection/hard-delete-by-filter`. API-key auth only
+     * (system operation); the query must be non-empty. Returns `{ ok, deletedCount }`.
+     */
+    async hardDeleteByFilter(collection, query) {
+        if (!query || Object.keys(query).length === 0) {
+            throw new Error('[coreApi] hardDeleteByFilter requires a non-empty query');
+        }
+        const url = `${this.baseUrl}/api/dynamic/${collection}/hard-delete-by-filter`;
+        const res = await fetch(url, { method: 'POST', headers: this.headers, body: JSON.stringify({ query }) });
+        if (!res.ok)
+            throw new CoreApiError('HARD_DELETE_BY_FILTER', collection, res.status, await safeText(res));
+        return (await res.json());
+    }
+    /**
+     * Atomically upsert a document by a single unique field, via core's
+     * server-side `POST /api/dynamic/:collection/upsert`. Returns the document
+     * (or `null`). Falls back to findBy + update/create on older cores that 404
+     * the upsert route. For composite keys / the full `{ ok, created }` result,
+     * use `upsertOn`.
      */
     async upsert(collection, matchField, matchValue, body) {
         const fullDoc = { ...body, [matchField]: matchValue };
@@ -165,6 +243,22 @@ export class CoreApiClient {
             return this.upsertLegacy(collection, matchField, matchValue, body);
         throw new CoreApiError('UPSERT', collection, res.status, await safeText(res));
     }
+    /**
+     * Atomically upsert by a COMPOSITE match key — `POST .../upsert` with
+     * `{ matchOn, document }`. Returns the full `{ ok, created, doc }` result so
+     * callers can branch on whether a row was created vs updated.
+     */
+    async upsertOn(collection, matchOn, document, opts) {
+        const url = `${this.baseUrl}/api/dynamic/${collection}/upsert`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.writeHeaders(opts),
+            body: JSON.stringify({ matchOn, document }),
+        });
+        if (!res.ok)
+            throw new CoreApiError('UPSERT_ON', collection, res.status, await safeText(res));
+        return (await res.json());
+    }
     async upsertLegacy(collection, matchField, matchValue, body) {
         const existing = await this.findBy(collection, matchField, matchValue);
         if (existing && typeof existing._id === 'string') {
@@ -194,6 +288,7 @@ export class CoreApiClient {
      * Upload a file to core's file API (`POST /api/files/uploadDirect`). Returns
      * the created file document (`{ _id, originalName }`) for referencing.
      * Accepts a `Uint8Array` (a Node `Buffer` is a `Uint8Array`, so it works too).
+     * To upload AS an end user, call `asUser(creds).uploadFile(...)`.
      */
     async uploadFile(data, opts) {
         const form = new FormData();
@@ -215,15 +310,38 @@ export class CoreApiClient {
             throw new CoreApiError('UPLOAD_FILE', opts.filename, res.status, await safeText(res));
         return (await res.json());
     }
+    /**
+     * Download a file's bytes — `GET /api/files/:id/content`. Returns the bytes
+     * plus content-type/filename, or `null` on 404. To download AS an end user,
+     * call `asUser(creds).downloadFile(...)`.
+     */
+    async downloadFile(fileId) {
+        const url = `${this.baseUrl}/api/files/${encodeURIComponent(fileId)}/content`;
+        const res = await fetch(url, { headers: this.headersWithoutContentType() });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new CoreApiError('DOWNLOAD_FILE', fileId, res.status, await safeText(res));
+        const data = new Uint8Array(await res.arrayBuffer());
+        const contentType = res.headers.get('content-type') ?? 'application/octet-stream';
+        const cd = res.headers.get('content-disposition') ?? '';
+        const m = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(cd);
+        return { data, contentType, filename: m?.[1] };
+    }
     /**
      * Decrypt `x-encrypted` fields for a record via core's internal decrypt
-     * endpoint. Returns a map of field name → plaintext, or `null` on failure.
+     * endpoint. Returns a map of field name → plaintext. By default returns
+     * `null` on failure; pass `{ throwOnError: true }` to throw `CoreApiError`
+     * instead. To decrypt AS an end user, call `asUser(creds).decrypt(...)`.
      */
-    async decrypt(collection, id) {
+    async decrypt(collection, id, opts) {
         const url = `${this.baseUrl}/api/internal/decrypt/${collection}/${encodeURIComponent(id)}`;
         const res = await fetch(url, { headers: this.headers });
-        if (!res.ok)
+        if (!res.ok) {
+            if (opts?.throwOnError)
+                throw new CoreApiError('DECRYPT', `${collection}/${id}`, res.status, await safeText(res));
             return null;
+        }
         return (await res.json());
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loynazkovacs/theitemapp-backend-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "description": "Server-side SDK for TheItemApp app backends: core API client, registration lifecycle, and auth verification.",