@x12i/memorix-client-api 0.18.0 → 0.20.0

package/dist/v1/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/v1/context.ts"],"names":[],"mappings":"AAgBA,MAAM,UAAU,OAAO,CAAC,GAAmB;IACzC,OAAO,GAA8B,CAAC;AACxC,CAAC"}

package/dist/v1/directory.d.ts

@@ -0,0 +1,26 @@
+import type { ClientScope } from "../scope.js";
+import { type Upstream } from "../upstream.js";
+export type DirectorySubject = {
+    recordId: string;
+    objectType: string;
+    dataCategory: string | null;
+    contentTypes: string[];
+};
+export type DirectoryPage = {
+    subjects: DirectorySubject[];
+    nextCursor: string | null;
+};
+/**
+ * One page of the record directory (`GET /api/data/subjects`, service 3.20.0).
+ * `null` when this Memorix does not serve the route.
+ */
+export declare function pageDirectory(upstream: Upstream, scope: ClientScope, objectType: string, page: {
+    limit: number;
+    cursor?: string;
+    withoutContent?: boolean;
+}): Promise<DirectoryPage | null>;
+/** Composed contents of each listed record, at most eight reads at a time. */
+export declare function composeSubjects(upstream: Upstream, scope: ClientScope, subjects: DirectorySubject[], wanted: string[], markdown: boolean): Promise<Map<string, Record<string, unknown>>>;
+/** True when Memorix pages the record directory. Reused for five minutes. */
+export declare function directoryPagingServed(upstream: Upstream, scope: ClientScope): Promise<boolean>;
+//# sourceMappingURL=directory.d.ts.map

package/dist/v1/directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../../src/v1/directory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAA0B,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEvE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAKxF;;;GAGG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAE,GACjE,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAiC/B;AAED,8EAA8E;AAC9E,wBAAsB,eAAe,CACnC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,EAAE,OAAO,GAChB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAqB/C;AAID,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAa9F"}

package/dist/v1/directory.js

@@ -0,0 +1,89 @@
+import { ApiError, UpstreamError } from "../errors.js";
+import { asRecord, upstreamCode } from "../upstream.js";
+const COMPOSE_CONCURRENCY = 8;
+const PROBE_TTL_MS = 5 * 60_000;
+/**
+ * One page of the record directory (`GET /api/data/subjects`, service 3.20.0).
+ * `null` when this Memorix does not serve the route.
+ */
+export async function pageDirectory(upstream, scope, objectType, page) {
+    const params = new URLSearchParams({ objectType, limit: String(page.limit) });
+    if (page.cursor)
+        params.set("cursor", page.cursor);
+    if (page.withoutContent)
+        params.set("withoutContent", "true");
+    let body;
+    try {
+        body = asRecord(await upstream.get(`/api/data/subjects?${params.toString()}`, scope));
+    }
+    catch (err) {
+        if (err instanceof UpstreamError) {
+            const code = upstreamCode(err);
+            if (code === "ROUTE_UNKNOWN_OBJECT_TYPE") {
+                throw new ApiError(404, "READ_NOT_FOUND", `Unknown object type ${objectType}`);
+            }
+            if (err.statusCode === 404 || err.statusCode === 501)
+                return null;
+        }
+        throw err;
+    }
+    if (!body || !Array.isArray(body.subjects))
+        return null;
+    const subjects = [];
+    for (const raw of body.subjects) {
+        const item = asRecord(raw);
+        if (!item || typeof item.recordId !== "string")
+            continue;
+        subjects.push({
+            recordId: item.recordId,
+            objectType: typeof item.objectType === "string" ? item.objectType : objectType,
+            dataCategory: typeof item.dataCategory === "string" ? item.dataCategory : null,
+            contentTypes: Array.isArray(item.contentTypes)
+                ? item.contentTypes.filter((ct) => typeof ct === "string")
+                : [],
+        });
+    }
+    const next = asRecord(body.pageInfo)?.nextCursor;
+    return { subjects, nextCursor: typeof next === "string" && next ? next : null };
+}
+/** Composed contents of each listed record, at most eight reads at a time. */
+export async function composeSubjects(upstream, scope, subjects, wanted, markdown) {
+    const out = new Map();
+    const queue = subjects
+        .map((subject) => ({ subject, contentTypes: subject.contentTypes.filter((ct) => wanted.includes(ct)) }))
+        .filter((item) => item.contentTypes.length > 0);
+    async function worker() {
+        for (let item = queue.shift(); item; item = queue.shift()) {
+            const composed = asRecord(await upstream.post("/api/data/compose", scope, {
+                explicit: true,
+                recordId: item.subject.recordId,
+                contentTypes: item.contentTypes,
+                ...(markdown ? { include: { markdown: true } } : {}),
+            }));
+            const contents = asRecord(asRecord(composed?.composition)?.contents);
+            if (contents)
+                out.set(item.subject.recordId, contents);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(COMPOSE_CONCURRENCY, queue.length) }, () => worker()));
+    return out;
+}
+const probes = new WeakMap();
+/** True when Memorix pages the record directory. Reused for five minutes. */
+export function directoryPagingServed(upstream, scope) {
+    const probe = probes.get(upstream);
+    if (probe && Date.now() - probe.at < PROBE_TTL_MS)
+        return probe.value;
+    const value = (async () => {
+        try {
+            await upstream.get("/api/data/subjects?objectType=__capability_probe__&limit=1", scope);
+            return true;
+        }
+        catch (err) {
+            return err instanceof UpstreamError && upstreamCode(err) === "ROUTE_UNKNOWN_OBJECT_TYPE";
+        }
+    })();
+    probes.set(upstream, { at: Date.now(), value });
+    return value;
+}
+//# sourceMappingURL=directory.js.map

package/dist/v1/directory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.js","sourceRoot":"","sources":["../../src/v1/directory.ts"],"names":[],"mappings":"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"}

package/dist/v1/discovery.d.ts

@@ -0,0 +1,24 @@
+import type { FastifyInstance } from "fastify";
+import type { V1Deps } from "./context.js";
+export declare const CONTRACT = "visualizer";
+export declare const CONTRACT_REVISION = "2026-10-24";
+export declare const SERVICE = "@x12i/memorix-client-api";
+export type Features = {
+    mapping: boolean;
+    census: boolean;
+    orgAgents: boolean;
+    relationshipPairs: boolean;
+    relationshipPairCounts: boolean;
+    sourceContentTypes: boolean;
+    partialListing: boolean;
+    conflictBodies: boolean;
+    directoryOnlyRecords: boolean;
+    conflictCensus: boolean;
+    directoryPaging: boolean;
+    planning: boolean;
+    packRevisions: boolean;
+    conditionalRefresh: boolean;
+};
+export declare function featuresFor(deps: V1Deps, orgId: string, caller: string): Promise<Features>;
+export declare function registerDiscoveryRoutes(app: FastifyInstance, deps: V1Deps): void;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/v1/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/v1/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,SAAS,CAAC;AAM/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAI3C,eAAO,MAAM,QAAQ,eAAe,CAAC;AACrC,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAC9C,eAAO,MAAM,OAAO,6BAA6B,CAAC;AAElD,MAAM,MAAM,QAAQ,GAAG;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,sBAAsB,EAAE,OAAO,CAAC;IAChC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,cAAc,EAAE,OAAO,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AAyBF,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CA4BhG;AAOD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAoHhF"}

package/dist/v1/discovery.js

@@ -0,0 +1,166 @@
+import { ApiError } from "../errors.js";
+import { orgFromToken } from "../scope.js";
+import { asRecord } from "../upstream.js";
+import { directoryPagingServed } from "./directory.js";
+import { queryOf, text } from "./http.js";
+export const CONTRACT = "visualizer";
+export const CONTRACT_REVISION = "2026-10-24";
+export const SERVICE = "@x12i/memorix-client-api";
+const AGENT_INFO_TTL_MS = 5 * 60_000;
+function headerValue(req, name) {
+    const raw = req.headers[name];
+    return (Array.isArray(raw) ? raw[0] : raw)?.trim() ?? "";
+}
+/** Org used for a call that does not select one: the header, else the token's only org. */
+function orgForProbe(req, claims) {
+    const requested = headerValue(req, "x-memorix-org-id");
+    if (claims) {
+        if (requested)
+            return orgFromToken(claims.organizationIds, requested);
+        return claims.organizationIds[0] ?? "";
+    }
+    return requested;
+}
+export async function featuresFor(deps, orgId, caller) {
+    let orgAgents = false;
+    let directoryPaging = false;
+    if (orgId) {
+        try {
+            orgAgents = (await deps.directory.deployed(orgId, caller)) !== null;
+        }
+        catch {
+            orgAgents = false;
+        }
+        directoryPaging = await directoryPagingServed(deps.upstream, { orgId, agentIds: ["*"], caller });
+    }
+    // Every composed read pairs with memorix-service 3.19.1, which also serves the org agent record (3.18.0).
+    return {
+        mapping: orgAgents,
+        census: orgAgents,
+        orgAgents,
+        relationshipPairs: orgAgents,
+        relationshipPairCounts: orgAgents,
+        sourceContentTypes: orgAgents,
+        partialListing: orgAgents,
+        conflictBodies: orgAgents,
+        directoryOnlyRecords: orgAgents,
+        conflictCensus: orgAgents,
+        directoryPaging,
+        planning: deps.planning !== null,
+        packRevisions: false,
+        conditionalRefresh: true,
+    };
+}
+function organizationEntry(id, claims) {
+    const name = claims?.organizationNames?.[id];
+    return name ? { id, name, nameStatus: "declared" } : { id, nameStatus: "unspecified" };
+}
+export function registerDiscoveryRoutes(app, deps) {
+    const agentInfo = new Map();
+    function infoOf(agentId, scope) {
+        const hit = agentInfo.get(agentId);
+        if (hit && Date.now() - hit.at < AGENT_INFO_TTL_MS)
+            return hit.value;
+        const value = (async () => {
+            const body = asRecord(await deps.upstream.get(`/api/metadata/raw?agentId=${encodeURIComponent(agentId)}`, {
+                orgId: scope.orgId,
+                agentIds: [agentId],
+                caller: scope.caller,
+            }));
+            const agent = asRecord(asRecord(body?.raw)?.agent);
+            const lineage = asRecord(body?.lineage);
+            return {
+                ...(typeof agent?.name === "string" && agent.name ? { name: agent.name } : {}),
+                ...(typeof agent?.description === "string" && agent.description ? { description: agent.description } : {}),
+                ...(typeof lineage?.checksum === "string"
+                    ? {
+                        pack: {
+                            checksum: lineage.checksum,
+                            ...(typeof lineage.installedAt === "string" ? { installedAt: lineage.installedAt } : {}),
+                            ...(typeof lineage.source === "string" ? { source: lineage.source } : {}),
+                        },
+                    }
+                    : {}),
+            };
+        })();
+        agentInfo.set(agentId, { at: Date.now(), value });
+        value.catch(() => agentInfo.delete(agentId));
+        return value;
+    }
+    app.get("/ready", async (_req, reply) => {
+        const memorix = await deps.probeMemorix();
+        if (!memorix)
+            return reply.status(503).send({ ok: false, service: SERVICE, memorix: "down" });
+        return { ok: true, service: SERVICE, auth: deps.authMode, memorix: "up" };
+    });
+    app.get("/api/v1/capabilities", async (req) => {
+        const { claims, caller } = await deps.authenticate(req);
+        const orgId = orgForProbe(req, claims);
+        return {
+            service: SERVICE,
+            api: "v1",
+            contract: CONTRACT,
+            contractRevision: CONTRACT_REVISION,
+            features: await featuresFor(deps, orgId, caller),
+            limits: {
+                pageLimitDefault: 50,
+                pageLimitMax: 200,
+                refBatchMax: 200,
+                upstreamTimeoutMs: 30_000,
+            },
+            rateLimit: null,
+        };
+    });
+    app.get("/api/v1/organizations", async (req) => {
+        const { claims } = await deps.authenticate(req);
+        const ids = claims ? claims.organizationIds : [headerValue(req, "x-memorix-org-id")].filter(Boolean);
+        return { organizations: ids.map((id) => organizationEntry(id, claims)) };
+    });
+    app.get("/api/v1/organization", async (req) => {
+        const scope = await deps.scopeFor(req, { agents: "none" });
+        const features = await featuresFor(deps, scope.orgId, scope.caller);
+        return {
+            organization: organizationEntry(scope.orgId, (await deps.authenticate(req)).claims),
+            capabilities: { census: features.census, sources: features.sourceContentTypes, planning: features.planning },
+        };
+    });
+    app.get("/api/v1/agents", async (req) => {
+        const scope = await deps.scopeFor(req, { agents: "none" });
+        const deployment = text(queryOf(req).deployment) ?? "org";
+        if (deployment !== "org" && deployment !== "platform") {
+            throw new ApiError(400, "VALIDATION", "deployment must be org or platform");
+        }
+        const deployed = await deps.directory.deployed(scope.orgId, scope.caller);
+        if (deployed === null && deployment === "org") {
+            throw new ApiError(501, "CAPABILITY_UNAVAILABLE", "Memorix keeps no org agent record", { feature: "orgAgents" });
+        }
+        const deployedIds = new Set((deployed ?? []).map((agent) => agent.id));
+        const listed = deployment === "org" ? (deployed ?? []) : await deps.directory.installed(scope.orgId, scope.caller);
+        const agents = await Promise.all(listed.map(async (agent) => {
+            let info = {};
+            try {
+                info = await infoOf(agent.id, scope);
+            }
+            catch {
+                info = {};
+            }
+            const deploymentState = deployment === "org" ? (agent.ok ? "deployed" : "missing") : deployedIds.has(agent.id) ? "deployed" : "installed";
+            return {
+                id: agent.id,
+                ...(info.name ? { name: info.name } : {}),
+                ...(info.description ? { description: info.description } : {}),
+                versionStatus: "unspecified",
+                ...(info.pack ? { pack: info.pack } : {}),
+                deploymentState,
+                resolution: { ok: agent.ok, error: agent.ok ? null : agent.error },
+                objectTypes: agent.ok ? agent.objectTypes : [],
+            };
+        }));
+        return {
+            scope: { orgId: scope.orgId, caller: scope.caller },
+            deployment,
+            agents,
+        };
+    });
+}
+//# sourceMappingURL=discovery.js.map

package/dist/v1/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/v1/discovery.ts"],"names":[],"mappings":"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"}

package/dist/v1/gaps.d.ts

@@ -0,0 +1,18 @@
+export type GapCategory = "empty" | "directory-only" | "not-measured" | "estimated" | "inaccessible" | "resolution-failure" | "unavailable" | "stale";
+export type Gap = {
+    code: string;
+    category: GapCategory;
+    orgId: string;
+    agentIds: string[];
+    /** Mapping section that was not returned: `counts`, `relationships`, `functions`, or `sources`. */
+    section?: "counts" | "relationships" | "functions" | "sources" | "objectTypes";
+    objectType?: string;
+    contentType?: string;
+    definitionId?: string;
+    sourceId?: string;
+    message?: string;
+    observedAt?: string;
+    retryable: boolean;
+    evidence?: Record<string, unknown>;
+};
+//# sourceMappingURL=gaps.d.ts.map

package/dist/v1/gaps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gaps.d.ts","sourceRoot":"","sources":["../../src/v1/gaps.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,gBAAgB,GAChB,cAAc,GACd,WAAW,GACX,cAAc,GACd,oBAAoB,GACpB,aAAa,GACb,OAAO,CAAC;AAEZ,MAAM,MAAM,GAAG,GAAG;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,WAAW,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,mGAAmG;IACnG,OAAO,CAAC,EAAE,QAAQ,GAAG,eAAe,GAAG,WAAW,GAAG,SAAS,GAAG,aAAa,CAAC;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC"}

package/dist/v1/gaps.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=gaps.js.map

package/dist/v1/gaps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gaps.js","sourceRoot":"","sources":["../../src/v1/gaps.ts"],"names":[],"mappings":""}

package/dist/v1/http.d.ts

@@ -0,0 +1,18 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+export declare function queryOf(req: FastifyRequest): Record<string, unknown>;
+export declare function text(raw: unknown): string | undefined;
+export declare function csv(raw: unknown): string[] | undefined;
+export declare function jsonQuery(raw: unknown, name: string): unknown;
+export declare function limitOf(raw: unknown, fallback?: number): number;
+export declare function boolQuery(raw: unknown, name: string, fallback?: boolean): boolean;
+export declare function wildcardParam(req: FastifyRequest): string;
+/** Path after `prefix` exactly as sent, before percent-decoding, so `%2F` stays inside one segment. */
+export declare function rawPathAfter(req: FastifyRequest, prefix: string): string | null;
+export declare function decodeSegments(raw: string): string;
+export declare function requestIdFrom(headerValue: string | string[] | undefined): string;
+export declare function etagOf(parts: unknown): string;
+/** Sends `body` with an `ETag`, or `304` with no body when `If-None-Match` matches. */
+export declare function sendWithEtag(req: FastifyRequest, reply: FastifyReply, body: unknown, tagParts: unknown): FastifyReply<import("fastify").RouteGenericInterface, import("fastify").RawServerDefault, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, unknown, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown>;
+/** Short stable id for a Memorix fingerprint string. */
+export declare function fingerprintId(raw: unknown): string | null;
+//# sourceMappingURL=http.d.ts.map

package/dist/v1/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/v1/http.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG5D,wBAAgB,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEpE;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIrD;AAED,wBAAgB,GAAG,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,GAAG,SAAS,CAItD;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ7D;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,SAAK,GAAG,MAAM,CAK3D;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAK/E;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAGzD;AAED,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK/E;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWlD;AAID,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,CAGhF;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE7C;AAYD,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,6RAKtG;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAGzD"}

package/dist/v1/http.js

@@ -0,0 +1,105 @@
+import { createHash, randomUUID } from "node:crypto";
+import { ApiError } from "../errors.js";
+export function queryOf(req) {
+    return (req.query ?? {});
+}
+export function text(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const value = raw.trim();
+    return value ? value : undefined;
+}
+export function csv(raw) {
+    if (typeof raw !== "string" || !raw.trim())
+        return undefined;
+    const items = raw.split(",").map((item) => item.trim()).filter(Boolean);
+    return items.length > 0 ? items : undefined;
+}
+export function jsonQuery(raw, name) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    if (typeof raw !== "string")
+        return raw;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new ApiError(400, "VALIDATION", `${name} must be JSON`);
+    }
+}
+export function limitOf(raw, fallback = 50) {
+    if (raw === undefined || raw === "")
+        return fallback;
+    const limit = Number(raw);
+    if (!Number.isFinite(limit))
+        throw new ApiError(400, "VALIDATION", "limit must be a number");
+    return Math.min(Math.max(Math.trunc(limit), 1), 200);
+}
+export function boolQuery(raw, name, fallback = false) {
+    if (raw === undefined || raw === "")
+        return fallback;
+    if (raw === true || raw === "true")
+        return true;
+    if (raw === false || raw === "false")
+        return false;
+    throw new ApiError(400, "VALIDATION", `${name} must be true or false`);
+}
+export function wildcardParam(req) {
+    const params = req.params;
+    return params["*"] ?? "";
+}
+/** Path after `prefix` exactly as sent, before percent-decoding, so `%2F` stays inside one segment. */
+export function rawPathAfter(req, prefix) {
+    const url = req.raw.url ?? req.url;
+    const path = url.split("?")[0] ?? "";
+    if (!path.startsWith(prefix))
+        return null;
+    return path.slice(prefix.length);
+}
+export function decodeSegments(raw) {
+    return raw
+        .split("/")
+        .map((segment) => {
+        try {
+            return decodeURIComponent(segment);
+        }
+        catch {
+            throw new ApiError(400, "VALIDATION", "path segment is not valid percent-encoding");
+        }
+    })
+        .join("/");
+}
+const REQUEST_ID = /^[\w.:\-/+=]{1,128}$/;
+export function requestIdFrom(headerValue) {
+    const raw = (Array.isArray(headerValue) ? headerValue[0] : headerValue)?.trim();
+    return raw && REQUEST_ID.test(raw) ? raw : randomUUID();
+}
+export function etagOf(parts) {
+    return `"${createHash("sha256").update(JSON.stringify(parts)).digest("base64url").slice(0, 27)}"`;
+}
+function etagMatches(header, etag) {
+    const raw = Array.isArray(header) ? header.join(",") : header;
+    if (!raw)
+        return false;
+    if (raw.trim() === "*")
+        return true;
+    return raw
+        .split(",")
+        .map((item) => item.trim().replace(/^W\//, ""))
+        .includes(etag);
+}
+/** Sends `body` with an `ETag`, or `304` with no body when `If-None-Match` matches. */
+export function sendWithEtag(req, reply, body, tagParts) {
+    const etag = etagOf(tagParts);
+    reply.header("etag", etag);
+    if (etagMatches(req.headers["if-none-match"], etag))
+        return reply.code(304).send();
+    return reply.send(body);
+}
+/** Short stable id for a Memorix fingerprint string. */
+export function fingerprintId(raw) {
+    if (typeof raw !== "string" || !raw)
+        return null;
+    return createHash("sha256").update(raw).digest("hex").slice(0, 16);
+}
+//# sourceMappingURL=http.js.map

package/dist/v1/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/v1/http.ts"],"names":[],"mappings":"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"}