@loynazkovacs/theitemapp-backend-sdk 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# @loynazkovacs/theitemapp-backend-sdk
+
+Server-side SDK for **TheItemApp app backends** — the counterpart to the
+frontend [`@loynazkovacs/theitemapp-platform-sdk`](../platform-sdk).
+
+Every app with its own backend (chat, coding-agent, vanda, music, image-generator,
+…) previously hand-rolled the same three things and let them drift:
+
+1. a `coreApiClient.ts` wrapping `/api/dynamic` CRUD,
+2. a registration / heartbeat / deregister loop in `index.ts`,
+3. an auth middleware proxying `/api/auth/me`.
+
+This package is the single canonical implementation of all three.
+
+> **Scope:** this SDK is for apps that run **their own backend**. Apps with no
+> backend ship via the [`seed-server`](../../images/seed-server) base image
+> instead and do not need this.
+
+## Install
+
+```bash
+npm install @loynazkovacs/theitemapp-backend-sdk
+```
+
+Requires Node ≥ 18 (uses the global `fetch`/`FormData`). Zero runtime dependencies.
+
+## Usage
+
+```ts
+import {
+  CoreApiClient,
+  startAppRegistration,
+  createFastifyAuthPreHandler, // or createExpressAuthMiddleware
+} from '@loynazkovacs/theitemapp-backend-sdk';
+import manifest from './dbseed/manifest.json' assert { type: 'json' };
+
+const coreUrl = process.env.CORE_API_URL ?? 'http://backend:3001';
+
+// 1. Core API client — key gets filled in by registration below.
+const coreApi = new CoreApiClient({ baseUrl: coreUrl, apiKey: null });
+
+// 2. Registration lifecycle: retry-until-up, heartbeat, deregister-on-exit.
+const registration = startAppRegistration({
+  coreUrl,
+  manifest,
+  selfUrl: process.env.SELF_URL ?? 'http://myapp:80',
+  registrationKey: process.env.APP_REGISTRATION_KEY,
+  onApiKey: (key) => coreApi.updateApiKey(key), // core rotates the key per register
+});
+
+// Wire core's reboot recovery kick into your own route:
+app.post('/app/re-register', async () => {
+  registration.reRegister();
+  return { ok: true };
+});
+
+// 3. Auth: verify users against core on protected routes.
+app.addHook('preHandler', createFastifyAuthPreHandler(coreUrl)); // sets request.user
+```
+
+### Framework-agnostic auth
+
+If you're not on Express/Fastify, call the core directly:
+
+```ts
+import { verifyUser, userInAnyGroup } from '@loynazkovacs/theitemapp-backend-sdk';
+
+const user = await verifyUser(coreUrl, { cookie, authorization });
+if (!user) return reply401();
+```
+
+## Exports
+
+| Export | Purpose |
+| --- | --- |
+| `CoreApiClient`, `CoreApiError` | Typed CRUD over `/api/dynamic` (+ file upload, decrypt, bulk-upsert, atomic upsert). |
+| `startAppRegistration` | Registration retry loop, API-key rotation capture, heartbeat, deregister, signal handlers. |
+| `verifyUser`, `normalizeId`, `userInAnyGroup` | Framework-agnostic auth primitives. |
+| `createExpressAuthMiddleware`, `createFastifyAuthPreHandler` | Drop-in middleware/preHandler. |
+
+## Not yet covered (roadmap)
+
+- `aggregate()` — core exposes pivot aggregation through the dynamic list route
+  (`_agg`), which isn't a clean stable HTTP contract yet. Use `list()` with
+  query params for now.
+- Seed/function HTTP serving — that belongs to apps without a backend, handled
+  by the `seed-server` image.
+
+## Publishing
+
+Same flow as the frontend SDK:
+
+```bash
+cd libs/backend-sdk
+npm run build      # tsc → dist/
+npm publish        # uses .npmrc registry + publishConfig (public)
+```

package/dist/auth.d.ts

@@ -0,0 +1,81 @@
+/**
+ * User authentication for app backends.
+ *
+ * App backends don't verify JWTs themselves — they forward the caller's
+ * 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.
+ */
+export type AuthUser = {
+    _id: string;
+    email?: string;
+    groupIds: string[];
+    /** The full `/api/auth/me` payload, for fields beyond the common ones. */
+    raw: Record<string, unknown>;
+};
+export type Credentials = {
+    cookie?: string;
+    authorization?: string;
+};
+export type VerifyOptions = {
+    /** Timeout for the core round-trip in ms (default 5000). */
+    timeoutMs?: number;
+};
+/**
+ * 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
+ * itself is unreachable (so callers can answer 503 vs 401 distinctly).
+ */
+export declare function verifyUser(coreUrl: string, creds: Credentials, opts?: VerifyOptions): Promise<AuthUser | null>;
+/**
+ * Normalize an id-ish value to a 24-hex string. Handles plain strings,
+ * `{ $oid }` extended-JSON, and Mongo `ObjectId`-like objects (anything with a
+ * sane `toString`). Returns `''` for null/undefined/unrecognized shapes.
+ *
+ * x-ref array fields on `items`-schema records come back as `ObjectId[]` from
+ * the driver even when typed `string[]` — always normalize before comparing
+ * against a `Set<string>` of group ids, or every check silently fails.
+ */
+export declare function normalizeId(value: unknown): string;
+type ReqWithHeaders = {
+    headers: {
+        cookie?: string;
+        authorization?: string;
+    };
+};
+interface ExpressResLike {
+    locals: Record<string, unknown>;
+    status(code: number): {
+        json(body: unknown): unknown;
+    };
+}
+type ExpressNext = (err?: unknown) => void;
+/**
+ * Express middleware: verifies the caller and stores the `AuthUser` on
+ * `res.locals[key]` (default `user`). Responds 401 (no/invalid credentials)
+ * or 503 (core unreachable) itself.
+ */
+export declare function createExpressAuthMiddleware(coreUrl: string, options?: {
+    localsKey?: string;
+} & VerifyOptions): (req: ReqWithHeaders, res: ExpressResLike, next: ExpressNext) => Promise<void>;
+interface FastifyReqLike extends ReqWithHeaders {
+    [k: string]: unknown;
+}
+interface FastifyReplyLike {
+    code(status: number): {
+        send(body: unknown): unknown;
+    };
+}
+/**
+ * Fastify preHandler: verifies the caller and assigns the `AuthUser` onto
+ * `request[key]` (default `user`). Responds 401/503 itself. Decorate your
+ * request (`app.decorateRequest('user', null)`) for typed access.
+ */
+export declare function createFastifyAuthPreHandler(coreUrl: string, options?: {
+    requestKey?: string;
+} & 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 {};
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +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,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,CA4B1B;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"}

package/dist/auth.js

@@ -0,0 +1,115 @@
+/**
+ * User authentication for app backends.
+ *
+ * App backends don't verify JWTs themselves — they forward the caller's
+ * 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.
+ */
+/**
+ * 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
+ * itself is unreachable (so callers can answer 503 vs 401 distinctly).
+ */
+export async function verifyUser(coreUrl, creds, opts = {}) {
+    if (!creds.cookie && !creds.authorization)
+        return null;
+    const meUrl = `${coreUrl.replace(/\/$/, '')}/api/auth/me`;
+    const headers = {};
+    if (creds.cookie)
+        headers.cookie = creds.cookie;
+    if (creds.authorization)
+        headers.authorization = creds.authorization;
+    const res = await fetch(meUrl, {
+        headers,
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 5_000),
+    });
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    const userId = normalizeId(data._id);
+    if (!userId)
+        return null;
+    const groupIds = Array.isArray(data.groupIds)
+        ? data.groupIds.map((g) => normalizeId(g)).filter((g) => g.length > 0)
+        : [];
+    return {
+        _id: userId,
+        email: typeof data.email === 'string' ? data.email : undefined,
+        groupIds,
+        raw: data,
+    };
+}
+/**
+ * Normalize an id-ish value to a 24-hex string. Handles plain strings,
+ * `{ $oid }` extended-JSON, and Mongo `ObjectId`-like objects (anything with a
+ * sane `toString`). Returns `''` for null/undefined/unrecognized shapes.
+ *
+ * x-ref array fields on `items`-schema records come back as `ObjectId[]` from
+ * the driver even when typed `string[]` — always normalize before comparing
+ * against a `Set<string>` of group ids, or every check silently fails.
+ */
+export function normalizeId(value) {
+    if (!value)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'object') {
+        const oid = value.$oid;
+        if (typeof oid === 'string')
+            return oid;
+        const str = String(value);
+        if (/^[a-f0-9]{24}$/i.test(str))
+            return str;
+    }
+    return '';
+}
+/**
+ * Express middleware: verifies the caller and stores the `AuthUser` on
+ * `res.locals[key]` (default `user`). Responds 401 (no/invalid credentials)
+ * or 503 (core unreachable) itself.
+ */
+export function createExpressAuthMiddleware(coreUrl, options = {}) {
+    const key = options.localsKey ?? 'user';
+    return async (req, res, next) => {
+        try {
+            const user = await verifyUser(coreUrl, { cookie: req.headers.cookie, authorization: req.headers.authorization }, options);
+            if (!user) {
+                res.status(401).json({ error: 'Unauthorized' });
+                return;
+            }
+            res.locals[key] = user;
+            next();
+        }
+        catch {
+            res.status(503).json({ error: 'Auth service unavailable' });
+        }
+    };
+}
+/**
+ * Fastify preHandler: verifies the caller and assigns the `AuthUser` onto
+ * `request[key]` (default `user`). Responds 401/503 itself. Decorate your
+ * request (`app.decorateRequest('user', null)`) for typed access.
+ */
+export function createFastifyAuthPreHandler(coreUrl, options = {}) {
+    const key = options.requestKey ?? 'user';
+    return async (request, reply) => {
+        try {
+            const user = await verifyUser(coreUrl, { cookie: request.headers.cookie, authorization: request.headers.authorization }, options);
+            if (!user) {
+                reply.code(401).send({ error: 'Unauthorized' });
+                return;
+            }
+            request[key] = user;
+        }
+        catch {
+            reply.code(503).send({ error: 'Auth service unavailable' });
+        }
+    };
+}
+/** True if the user belongs to any of the given group ids. */
+export function userInAnyGroup(user, groupIds) {
+    const set = groupIds instanceof Set ? groupIds : new Set(groupIds);
+    return user.groupIds.some((id) => set.has(id));
+}

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

@@ -0,0 +1,121 @@
+/**
+ * CoreApiClient — a thin, typed client over core's `/api/dynamic/<collection>`
+ * CRUD surface (plus the file-upload 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
+ * handling. This is the canonical, general implementation.
+ *
+ * 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.
+ */
+export declare class CoreApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(method: string, target: string, status: number, body: string);
+}
+export type CoreApiConfig = {
+    /** Core API base URL, e.g. `http://backend:3001`. Trailing slash is trimmed. */
+    baseUrl: string;
+    /** Functional API key. May be `null` until registration provisions one. */
+    apiKey?: string | null;
+    /**
+     * Send `x-theitemapp-skip-webhooks: 1` on writes (default `true`). Set
+     * `false` if your writes should trigger webhook/automation fan-out.
+     */
+    skipWebhooks?: boolean;
+};
+export type BulkUpsertResult = {
+    upsertedCount: number;
+    modifiedCount: number;
+    errors: Array<{
+        index: number;
+        error: string;
+    }>;
+};
+export type UploadFileOptions = {
+    filename: string;
+    mimeType: string;
+    kind?: 'file' | 'image';
+    visibility?: 'private' | 'groups' | 'everyone';
+    groupIds?: string[];
+    title?: string;
+};
+export declare class CoreApiClient {
+    private readonly baseUrl;
+    private readonly skipWebhooks;
+    private readonly headers;
+    constructor(config: CoreApiConfig);
+    /** Replace the functional API key (e.g. after core rotates it on re-registration). */
+    updateApiKey(apiKey: string): void;
+    /** Current functional API key (empty string if none set yet). */
+    getApiKey(): string;
+    /** Whether a non-empty API key is present — gate writes on this post-registration. */
+    isReady(): boolean;
+    /** Headers minus `Content-Type` — for requests with no JSON body (DELETE) or multipart. */
+    private headersWithoutContentType;
+    /**
+     * List documents. `query` maps to core's dynamic list params, e.g.
+     * `{ _l: '50', _s: '-createdAt', someField: 'x' }`. Defaults to `_l=500`.
+     */
+    list<T = Record<string, unknown>>(collection: string, query?: Record<string, string>): Promise<T[]>;
+    /**
+     * 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".
+     */
+    get<T = Record<string, unknown>>(collection: string, id: string): 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
+     * "not found").
+     */
+    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>;
+    /** 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 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.
+     */
+    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.
+     */
+    upsert<T = Record<string, unknown>>(collection: string, matchField: string, matchValue: string, body: Record<string, unknown>): Promise<T | null>;
+    private upsertLegacy;
+    /**
+     * Bulk-upsert up to 500 documents, matched by a composite key (typically
+     * `['_id']`). Returns core's `{ upsertedCount, modifiedCount, errors }`
+     * summary. Throws `CoreApiError` on transport/protocol failure.
+     */
+    bulkUpsert(collection: string, matchOn: string[], documents: Record<string, unknown>[]): Promise<BulkUpsertResult>;
+    /**
+     * 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).
+     */
+    uploadFile(data: Uint8Array, opts: UploadFileOptions): Promise<{
+        _id: string;
+        originalName: string;
+    }>;
+    /**
+     * Decrypt `x-encrypted` fields for a record via core's internal decrypt
+     * endpoint. Returns a map of field name → plaintext, or `null` on failure.
+     */
+    decrypt(collection: string, id: string): Promise<Record<string, string | null> | null>;
+}
+//# sourceMappingURL=core-api-client.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,237 @@
+/**
+ * CoreApiClient — a thin, typed client over core's `/api/dynamic/<collection>`
+ * CRUD surface (plus the file-upload 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
+ * handling. This is the canonical, general implementation.
+ *
+ * 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.
+ */
+export class CoreApiError extends Error {
+    status;
+    body;
+    constructor(method, target, status, body) {
+        super(`[coreApi] ${method} ${target} failed: ${status} — ${body.slice(0, 300)}`);
+        this.name = 'CoreApiError';
+        this.status = status;
+        this.body = body;
+    }
+}
+export class CoreApiClient {
+    baseUrl;
+    skipWebhooks;
+    headers;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, '');
+        this.skipWebhooks = config.skipWebhooks ?? true;
+        this.headers = {
+            'Content-Type': 'application/json',
+            ...(config.apiKey ? { 'x-api-key': config.apiKey } : {}),
+            ...(this.skipWebhooks ? { 'x-theitemapp-skip-webhooks': '1' } : {}),
+        };
+    }
+    /** Replace the functional API key (e.g. after core rotates it on re-registration). */
+    updateApiKey(apiKey) {
+        this.headers['x-api-key'] = apiKey;
+    }
+    /** Current functional API key (empty string if none set yet). */
+    getApiKey() {
+        return this.headers['x-api-key'] ?? '';
+    }
+    /** Whether a non-empty API key is present — gate writes on this post-registration. */
+    isReady() {
+        return (this.headers['x-api-key']?.length ?? 0) > 0;
+    }
+    /** Headers minus `Content-Type` — for requests with no JSON body (DELETE) or multipart. */
+    headersWithoutContentType() {
+        const { 'Content-Type': _ct, ...rest } = this.headers;
+        return rest;
+    }
+    /**
+     * List documents. `query` maps to core's dynamic list params, e.g.
+     * `{ _l: '50', _s: '-createdAt', someField: 'x' }`. Defaults to `_l=500`.
+     */
+    async list(collection, query) {
+        const params = new URLSearchParams({ _l: '500', ...query });
+        const url = `${this.baseUrl}/api/dynamic/${collection}?${params.toString()}`;
+        const res = await fetch(url, { headers: this.headers });
+        if (!res.ok)
+            throw new CoreApiError('LIST', collection, res.status, await safeText(res));
+        const data = await res.json();
+        return Array.isArray(data) ? data : [];
+    }
+    /**
+     * 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".
+     */
+    async get(collection, id) {
+        const url = `${this.baseUrl}/api/dynamic/${collection}/${encodeURIComponent(id)}`;
+        const res = await fetch(url, { headers: this.headers });
+        if (res.ok)
+            return (await res.json());
+        if (res.status === 404)
+            return null;
+        throw new CoreApiError('GET', `${collection}/${id}`, res.status, await safeText(res));
+    }
+    /**
+     * Find a single document by an indexed field. Returns `null` for no match;
+     * throws `CoreApiError` on transient failure (never masks a read error as
+     * "not found").
+     */
+    async findBy(collection, field, value) {
+        const params = new URLSearchParams({ [field]: value, _l: '1' });
+        const url = `${this.baseUrl}/api/dynamic/${collection}?${params.toString()}`;
+        const res = await fetch(url, { headers: this.headers });
+        if (!res.ok)
+            throw new CoreApiError('FINDBY', collection, res.status, await safeText(res));
+        const data = (await res.json());
+        return Array.isArray(data) ? (data[0] ?? null) : null;
+    }
+    /** Create a document. Throws `CoreApiError` on failure. */
+    async create(collection, body) {
+        const url = `${this.baseUrl}/api/dynamic/${collection}`;
+        const res = await fetch(url, { method: 'POST', headers: this.headers, body: JSON.stringify(body) });
+        if (!res.ok)
+            throw new CoreApiError('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) {
+        const url = `${this.baseUrl}/api/dynamic/${collection}/${encodeURIComponent(id)}`;
+        const res = await fetch(url, { method: 'PUT', headers: this.headers, body: JSON.stringify(body) });
+        if (!res.ok)
+            throw new CoreApiError('UPDATE', `${collection}/${id}`, res.status, await safeText(res));
+        return (await res.json());
+    }
+    /**
+     * 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.
+     */
+    async updateAsUser(collection, id, body, userJwt) {
+        const url = `${this.baseUrl}/api/dynamic/${collection}/${encodeURIComponent(id)}`;
+        const res = await fetch(url, {
+            method: 'PUT',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${userJwt}`,
+                ...(this.skipWebhooks ? { 'x-theitemapp-skip-webhooks': '1' } : {}),
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            throw new CoreApiError('UPDATE_AS_USER', `${collection}/${id}`, res.status, await safeText(res));
+        }
+        return (await res.json());
+    }
+    /** Soft-delete a document by id. Returns `true` on success or 404 (already gone). */
+    async delete(collection, id) {
+        const url = `${this.baseUrl}/api/dynamic/${collection}/${encodeURIComponent(id)}`;
+        // No Content-Type / body — Fastify rejects an empty JSON body
+        // (FST_ERR_CTP_EMPTY_JSON_BODY).
+        const res = await fetch(url, { method: 'DELETE', headers: this.headersWithoutContentType() });
+        if (res.ok || res.status === 404)
+            return true;
+        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.
+     */
+    async upsert(collection, matchField, matchValue, body) {
+        const fullDoc = { ...body, [matchField]: matchValue };
+        const url = `${this.baseUrl}/api/dynamic/${collection}/upsert`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify({ matchOn: [matchField], document: fullDoc }),
+        });
+        if (res.ok) {
+            const json = (await res.json());
+            return json.doc ?? null;
+        }
+        if (res.status === 404)
+            return this.upsertLegacy(collection, matchField, matchValue, body);
+        throw new CoreApiError('UPSERT', collection, res.status, await safeText(res));
+    }
+    async upsertLegacy(collection, matchField, matchValue, body) {
+        const existing = await this.findBy(collection, matchField, matchValue);
+        if (existing && typeof existing._id === 'string') {
+            return this.update(collection, existing._id, body);
+        }
+        return this.create(collection, { ...body, [matchField]: matchValue });
+    }
+    /**
+     * Bulk-upsert up to 500 documents, matched by a composite key (typically
+     * `['_id']`). Returns core's `{ upsertedCount, modifiedCount, errors }`
+     * summary. Throws `CoreApiError` on transport/protocol failure.
+     */
+    async bulkUpsert(collection, matchOn, documents) {
+        if (documents.length === 0)
+            return { upsertedCount: 0, modifiedCount: 0, errors: [] };
+        const url = `${this.baseUrl}/api/dynamic/${collection}/bulk-upsert`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify({ matchOn, documents }),
+        });
+        if (!res.ok)
+            throw new CoreApiError('BULK_UPSERT', collection, res.status, await safeText(res));
+        return (await res.json());
+    }
+    /**
+     * 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).
+     */
+    async uploadFile(data, opts) {
+        const form = new FormData();
+        // Metadata fields MUST precede the file blob — @fastify/multipart stops
+        // reading fields once the file stream is consumed.
+        form.append('kind', opts.kind ?? 'file');
+        form.append('visibility', opts.visibility ?? 'everyone');
+        if (opts.title)
+            form.append('title', opts.title);
+        if (opts.groupIds?.length)
+            form.append('groupIds', opts.groupIds.join(','));
+        // `data` is a valid BlobPart at runtime; the cast sidesteps the DOM lib's
+        // SharedArrayBuffer-vs-ArrayBuffer strictness on `Uint8Array`.
+        form.append('file', new Blob([data], { type: opts.mimeType }), opts.filename);
+        // Let FormData set the multipart Content-Type (with boundary).
+        const url = `${this.baseUrl}/api/files/uploadDirect`;
+        const res = await fetch(url, { method: 'POST', headers: this.headersWithoutContentType(), body: form });
+        if (!res.ok)
+            throw new CoreApiError('UPLOAD_FILE', opts.filename, res.status, await safeText(res));
+        return (await res.json());
+    }
+    /**
+     * Decrypt `x-encrypted` fields for a record via core's internal decrypt
+     * endpoint. Returns a map of field name → plaintext, or `null` on failure.
+     */
+    async decrypt(collection, id) {
+        const url = `${this.baseUrl}/api/internal/decrypt/${collection}/${encodeURIComponent(id)}`;
+        const res = await fetch(url, { headers: this.headers });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+}
+async function safeText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return '';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './core-api-client.js';
+export * from './registration.js';
+export * from './auth.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './core-api-client.js';
+export * from './registration.js';
+export * from './auth.js';

package/dist/registration.d.ts

@@ -0,0 +1,73 @@
+/**
+ * App registration lifecycle.
+ *
+ * Every app backend must register itself with core so core inserts an `apps`
+ * catalog row, runs the app's seeds, and provisions the app's functional API
+ * key. The shape of that handshake — POST `/api/apps/register`, capture the
+ * rotated `apiKey`, retry until core is up, re-register on core's reboot,
+ * heartbeat every 5 minutes, deregister on shutdown — was copy-pasted into
+ * every backend's `index.ts`. This is the canonical implementation.
+ *
+ * The helper is HTTP-framework-agnostic: it owns the timers and process
+ * signal handlers, and hands you back a `reRegister()` you wire into your own
+ * `POST /app/re-register` route.
+ */
+export type AppManifest = {
+    appKey: string;
+    appVersion?: string;
+    [k: string]: unknown;
+};
+export type RegistrationLogger = {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+};
+export type RegistrationOptions = {
+    /** Core API base URL, e.g. `http://backend:3001`. */
+    coreUrl: string;
+    /** The app's seed manifest (must contain `appKey`). */
+    manifest: AppManifest;
+    /** How core reaches this container, e.g. `http://myapp:80`. */
+    selfUrl: string;
+    /**
+     * Shared registration secret (`X-Registration-Key` header). Required by
+     * cores that gate app registration; omit for open local stacks.
+     */
+    registrationKey?: string | null;
+    /**
+     * Called whenever core returns a freshly provisioned/rotated functional
+     * API key. Wire this to `coreApi.updateApiKey`.
+     */
+    onApiKey?: (apiKey: string) => void;
+    /** Retry attempts while core is still booting (default 30). */
+    maxRetries?: number;
+    /** Delay between retries in ms (default 5000). */
+    retryIntervalMs?: number;
+    /** Heartbeat interval in ms (default 5 min). Set `0` to disable. */
+    heartbeatMs?: number;
+    /** Install SIGTERM/SIGINT handlers that deregister + exit (default true). */
+    installSignalHandlers?: boolean;
+    /** Logger (default `console`). */
+    logger?: RegistrationLogger;
+};
+export type RegistrationHandle = {
+    /** Run one registration attempt now. Resolves `true` on success. */
+    register: () => Promise<boolean>;
+    /**
+     * Fire-and-forget re-registration — wire into your `POST /app/re-register`
+     * route. Returns immediately; the registration runs in the background.
+     */
+    reRegister: () => void;
+    /** Deregister from core (best-effort). */
+    deregister: () => Promise<void>;
+    /** Stop the heartbeat timer (does not deregister). */
+    stop: () => void;
+};
+/**
+ * Start the registration lifecycle. Kicks off a background retry loop
+ * immediately (does not block your server's `listen`), starts the heartbeat,
+ * and — unless disabled — installs shutdown handlers. Returns a handle you use
+ * to wire the `/app/re-register` route and to control shutdown.
+ */
+export declare function startAppRegistration(opts: RegistrationOptions): RegistrationHandle;
+//# sourceMappingURL=registration.d.ts.map

package/dist/registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,QAAQ,EAAE,WAAW,CAAC;IACtB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,kCAAkC;IAClC,MAAM,CAAC,EAAE,kBAAkB,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC;;;OAGG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,sDAAsD;IACtD,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAIF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,mBAAmB,GAAG,kBAAkB,CAmGlF"}

package/dist/registration.js

@@ -0,0 +1,119 @@
+/**
+ * App registration lifecycle.
+ *
+ * Every app backend must register itself with core so core inserts an `apps`
+ * catalog row, runs the app's seeds, and provisions the app's functional API
+ * key. The shape of that handshake — POST `/api/apps/register`, capture the
+ * rotated `apiKey`, retry until core is up, re-register on core's reboot,
+ * heartbeat every 5 minutes, deregister on shutdown — was copy-pasted into
+ * every backend's `index.ts`. This is the canonical implementation.
+ *
+ * The helper is HTTP-framework-agnostic: it owns the timers and process
+ * signal handlers, and hands you back a `reRegister()` you wire into your own
+ * `POST /app/re-register` route.
+ */
+const REGISTER_PATH = '/api/apps/register';
+/**
+ * Start the registration lifecycle. Kicks off a background retry loop
+ * immediately (does not block your server's `listen`), starts the heartbeat,
+ * and — unless disabled — installs shutdown handlers. Returns a handle you use
+ * to wire the `/app/re-register` route and to control shutdown.
+ */
+export function startAppRegistration(opts) {
+    const coreUrl = opts.coreUrl.replace(/\/$/, '');
+    const appKey = opts.manifest.appKey;
+    const log = opts.logger ?? console;
+    const maxRetries = opts.maxRetries ?? 30;
+    const retryIntervalMs = opts.retryIntervalMs ?? 5_000;
+    const heartbeatMs = opts.heartbeatMs ?? 5 * 60 * 1000;
+    const installSignals = opts.installSignalHandlers ?? true;
+    // Last issued key prefix — sent back so core rotates the SAME key rather
+    // than minting a new one on every re-registration.
+    let currentKeyPrefix = null;
+    let heartbeatTimer = null;
+    const register = async () => {
+        const body = { manifest: opts.manifest, baseUrl: opts.selfUrl };
+        if (currentKeyPrefix)
+            body.apiKeyPrefix = currentKeyPrefix;
+        try {
+            const res = await fetch(`${coreUrl}${REGISTER_PATH}`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(opts.registrationKey ? { 'X-Registration-Key': opts.registrationKey } : {}),
+                },
+                body: JSON.stringify(body),
+            });
+            if (!res.ok) {
+                log.warn(`[${appKey}] Registration failed: ${res.status} ${res.statusText}`);
+                return false;
+            }
+            const data = (await res.json());
+            if (data.apiKey) {
+                currentKeyPrefix = String(data.apiKey).slice(0, 8);
+                opts.onApiKey?.(data.apiKey);
+            }
+            log.info(`[${appKey}] Registered with core (engine: ${data.engineVersion ?? 'unknown'})`);
+            return true;
+        }
+        catch {
+            // Core not reachable yet — caller's retry loop handles it.
+            return false;
+        }
+    };
+    const retryUntilRegistered = async () => {
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            if (await register())
+                return;
+            log.info(`[${appKey}] Core not ready, retrying (${attempt}/${maxRetries})...`);
+            await delay(retryIntervalMs);
+        }
+        log.error(`[${appKey}] Failed to register with core after ${maxRetries} attempts`);
+    };
+    const deregister = async () => {
+        try {
+            await fetch(`${coreUrl}${REGISTER_PATH}/${appKey}`, { method: 'DELETE' });
+            log.info(`[${appKey}] Deregistered from core`);
+        }
+        catch {
+            // Best effort — core might already be down.
+        }
+    };
+    // Kick registration in the background — never block startup.
+    void retryUntilRegistered();
+    // Heartbeat: re-register periodically. Registration is idempotent on core's
+    // side and refreshes the rotated API key, recovering from a missed
+    // `/app/re-register` kick or a core reconcile-loop catalog drop.
+    if (heartbeatMs > 0) {
+        heartbeatTimer = setInterval(() => {
+            void register();
+        }, heartbeatMs);
+        heartbeatTimer.unref?.();
+    }
+    const stop = () => {
+        if (heartbeatTimer) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = null;
+        }
+    };
+    if (installSignals) {
+        const shutdown = async () => {
+            stop();
+            await deregister();
+            process.exit(0);
+        };
+        process.on('SIGTERM', () => void shutdown());
+        process.on('SIGINT', () => void shutdown());
+    }
+    return {
+        register,
+        reRegister: () => {
+            void register();
+        },
+        deregister,
+        stop,
+    };
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@loynazkovacs/theitemapp-backend-sdk",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Server-side SDK for TheItemApp app backends: core API client, registration lifecycle, and auth verification.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LoynazKovacs/TheItemApp.git",
+    "directory": "libs/backend-sdk"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.2"
+  }
+}