@yargote/artifacts-client 0.0.0-stage → 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yerson Argote
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# Artifacts HTTP client reference
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@yargote/artifacts-client` is a typed Fetch client for the Artifacts REST API. It depends on `@yargote/artifacts-contracts` and Zod. It does not install the artifact store or a database driver. Node 24 or later is required.
+
+```sh
+npm install @yargote/artifacts-client@0.1.0-beta.1
+```
+
+```ts
+import { createArtifactHttpClient, HttpError } from '@yargote/artifacts-client';
+
+const client = createArtifactHttpClient({
+	resource: process.env.ARTIFACTS_SERVER!,
+	accessToken: async () => obtainAccessToken(),
+	timeoutMs: 30_000,
+});
+
+const identity = await client.identity();
+const document = await client.read({ artifactId: 'artifact-id' });
+```
+
+## Configuration
+
+`createArtifactHttpClient({ resource, accessToken, fetch?, timeoutMs? })` returns an `ArtifactHttpClient`.
+
+`resource` is the exact canonical OAuth resource. A resource ending in `/mcp` uses REST routes under `/mcp/v1`. HTTPS is required except for HTTP on `localhost`, `127.0.0.1`, or `[::1]`. Credentials, queries, fragments, and noncanonical URLs are rejected. The client has no default resource.
+
+`accessToken` is a bearer token or an asynchronous function that returns one. The function runs once per method call. The caller owns credential storage and refresh.
+
+`fetch` defaults to `globalThis.fetch`. `timeoutMs` defaults to 30 seconds and covers the request and response body. It must be a positive safe integer no greater than 2147483647.
+
+## Methods
+
+Every method makes one HTTP request. The client does not retry, follow redirects, rebase conflicts, or change expected versions.
+
+| Method | Input | Result |
+| --- | --- | --- |
+| `identity()` | None | Verified user, session, client, and scopes |
+| `create(command)` | `requestId`, complete `snapshot`, optional `response` | Artifact receipt |
+| `list(query?)` | Optional `limit` and `cursor` | Artifact summaries and `nextCursor` |
+| `read(query)` | `artifactId`, optional `revisionId` and `response` | Artifact revision |
+| `update(command)` | `requestId`, `artifactId`, `expectedRevisionId`, complete `snapshot`, optional `response` | Artifact receipt |
+| `history(query)` | `artifactId`, optional `limit`, `beforeSequence`, and `response` | Revisions and `nextBeforeSequence` |
+| `publish(command)` | `requestId`, `artifactId`, `revisionId`, `expectedPublicationVersion` | Publication receipt |
+| `export(query)` | `artifactId`, `revisionId` | `{ filename, mediaType, bytes, sha256 }` |
+
+Create, read, and update accept `response: 'compact'`. The returned revision contains metadata and file summaries. Omitted response and `response: 'full'` return the complete snapshot. History accepts `response: 'summary'` or `response: 'full'`. Its page limit is ten revisions. Overloads reflect these projections in the return type.
+
+All commands and JSON responses pass the strict domain schemas. An omitted mutation `response` remains omitted in the transmitted command. JSON responses are bounded at 64 MiB, which accommodates ten maximum-size revisions with JSON escaping. Archives are bounded at 8 MiB. Export verifies the binary bytes against `X-Artifact-SHA256` and returns the bytes without rebuilding the ZIP.
+
+`prepareArtifactEdit(client, { artifactId, requestId, changes })` reads the current full snapshot and prepares an immutable update command. Metadata and content changes merge into that snapshot. An explicit `files` array replaces the attachments. The helper does not submit the update. Retain its exact output before sending it.
+
+## Errors and retries
+
+`HttpError` extends `Error` and contains `status`, `code`, and `details`. Server conflicts preserve the server's details. Transport failures use status `0` and code `network_error` or `timeout`. Rejected redirects use `redirect_refused`. Invalid response schemas use `invalid_response`. Oversized responses use `response_too_large`. A mismatched archive digest uses `archive_digest_mismatch`.
+
+Invalid local commands throw a Zod validation error before any HTTP request. Invalid configuration throws `TypeError`.
+
+A caller that needs recovery retains the complete create, update, or publish command before its first request. Retrying that exact command returns the original receipt. Changing `response`, the snapshot, or any expected version changes the command. A conflict requires a new deliberate command with a new request ID. A replayed receipt describes the original operation and can differ from a fresh read.
+
+## Compiled installation
+
+The registry package contains compiled ESM JavaScript and declarations. Consumers need no TypeScript loader or database package. For repository development, `pnpm build:packages` produces local tarballs and a `dist/packages/manifest.json` inventory. `pnpm test:packages` verifies an ordinary Node consumer and its types.
+
+This package is MIT licensed. The license applies to this package and does not license the private Artifacts application repository.

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@yargote/artifacts-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.1",
+  "private": false,
+  "type": "module",
+  "description": "Typed HTTP client for the Artifacts REST API.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yersonargotev/artifacts.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/yersonargotev",
+  "bugs": {
+    "url": "https://github.com/yersonargotev"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@yargote/artifacts-contracts": "0.1.0-beta.1",
+    "zod": "4.6.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta",
+    "provenance": false
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { createSchema, exportSchema, historySchema, listSchema, publishResultSchema, publishSchema, readSchema, type ArtifactRead, type UpdateInput } from '@yargote/artifacts-contracts';
+import { historyResultSchema, listResultSchema, summaryHistoryResultSchema, type Identity } from '@yargote/artifacts-contracts/http';
+import type { CompactArtifactRead } from '@yargote/artifacts-contracts/workflow';
+export type { ArtifactRead, Snapshot, UpdateInput } from '@yargote/artifacts-contracts';
+export type { Identity } from '@yargote/artifacts-contracts/http';
+export type { CompactArtifactRead, RevisionSummary } from '@yargote/artifacts-contracts/workflow';
+export { prepareArtifactEdit } from '@yargote/artifacts-contracts/workflow';
+export type CreateInput = z.input<typeof createSchema>;
+export type ReadInput = z.input<typeof readSchema>;
+export type PublishInput = z.input<typeof publishSchema>;
+export type ListInput = z.input<typeof listSchema>;
+export type HistoryInput = z.input<typeof historySchema>;
+export type ExportInput = z.input<typeof exportSchema>;
+export type ArtifactArchive = {
+    filename: string;
+    mediaType: 'application/zip';
+    bytes: Uint8Array;
+    sha256: string;
+};
+export type HistoryResult = z.infer<typeof historyResultSchema>;
+export type SummaryHistoryResult = z.infer<typeof summaryHistoryResultSchema>;
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown>, options?: ErrorOptions);
+}
+export interface ArtifactHttpClient {
+    identity(): Promise<Identity>;
+    create(input: CreateInput & {
+        response: 'compact';
+    }): Promise<CompactArtifactRead>;
+    create(input: CreateInput & {
+        response?: 'full';
+    }): Promise<ArtifactRead>;
+    create(input: CreateInput): Promise<ArtifactRead | CompactArtifactRead>;
+    list(input?: ListInput): Promise<z.infer<typeof listResultSchema>>;
+    read(input: ReadInput & {
+        response: 'compact';
+    }): Promise<CompactArtifactRead>;
+    read(input: ReadInput & {
+        response?: 'full';
+    }): Promise<ArtifactRead>;
+    read(input: ReadInput): Promise<ArtifactRead | CompactArtifactRead>;
+    update(input: UpdateInput & {
+        response: 'compact';
+    }): Promise<CompactArtifactRead>;
+    update(input: UpdateInput & {
+        response?: 'full';
+    }): Promise<ArtifactRead>;
+    update(input: UpdateInput): Promise<ArtifactRead | CompactArtifactRead>;
+    history(input: HistoryInput & {
+        response: 'summary';
+    }): Promise<SummaryHistoryResult>;
+    history(input: HistoryInput & {
+        response?: 'full';
+    }): Promise<HistoryResult>;
+    history(input: HistoryInput): Promise<HistoryResult | SummaryHistoryResult>;
+    publish(input: PublishInput): Promise<z.infer<typeof publishResultSchema>>;
+    export(input: ExportInput): Promise<ArtifactArchive>;
+}
+export declare function createArtifactHttpClient(options: {
+    resource: string;
+    accessToken: string | (() => Promise<string>);
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}): ArtifactHttpClient;

package/src/index.js

@@ -0,0 +1,175 @@
+import { z } from 'zod';
+import { artifactReadSchema, createSchema, exportSchema, historySchema, listSchema, publishResultSchema, publishSchema, readSchema, updateSchema } from '@yargote/artifacts-contracts';
+import { compactArtifactReadSchema, historyResultSchema, httpErrorSchema, identitySchema, listResultSchema, restBase, summaryHistoryResultSchema } from '@yargote/artifacts-contracts/http';
+export { prepareArtifactEdit } from '@yargote/artifacts-contracts/workflow';
+export class HttpError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details = {}, options) {
+        super(message, options);
+        this.name = 'HttpError';
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+const maxJsonBytes = 64 * 1024 * 1024;
+const maxArchiveBytes = 8 * 1024 * 1024;
+async function boundedBytes(response, maximum) {
+    const length = response.headers.get('content-length');
+    if (length !== null && (!/^\d+$/.test(length) || Number(length) > maximum)) {
+        await response.body?.cancel();
+        throw new HttpError(response.status, 'response_too_large', 'The server response exceeds the size limit');
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        return new Uint8Array();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            size += next.value.byteLength;
+            if (size > maximum) {
+                await reader.cancel();
+                throw new HttpError(response.status, 'response_too_large', 'The server response exceeds the size limit');
+            }
+            chunks.push(next.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+function query(values) {
+    const parameters = new URLSearchParams();
+    for (const [key, value] of Object.entries(values))
+        if (value !== undefined)
+            parameters.set(key, String(value));
+    const encoded = parameters.toString();
+    return encoded ? `?${encoded}` : '';
+}
+function parseResponse(schema, value, status) {
+    const result = schema.safeParse(value);
+    if (!result.success)
+        throw new HttpError(status, 'invalid_response', 'The server returned an invalid response');
+    return result.data;
+}
+export function createArtifactHttpClient(options) {
+    const base = restBase(options.resource);
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
+        throw new TypeError('timeoutMs must be a positive integer no greater than 2147483647');
+    async function request(path, method, parse, input, maximum = maxJsonBytes) {
+        const token = typeof options.accessToken === 'string' ? options.accessToken : await options.accessToken();
+        if (!token || /[\r\n]/.test(token))
+            throw new TypeError('A nonempty access token is required');
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetcher(`${base}${path}`, {
+                method,
+                redirect: 'manual',
+                signal: controller.signal,
+                headers: { authorization: `Bearer ${token}`, accept: maximum === maxArchiveBytes ? 'application/zip, application/json' : 'application/json', ...(input === undefined ? {} : { 'content-type': 'application/json' }) },
+                ...(input === undefined ? {} : { body: JSON.stringify(input) }),
+            });
+            if (response.status >= 300 && response.status < 400) {
+                await response.body?.cancel();
+                throw new HttpError(response.status, 'redirect_refused', 'The server attempted to redirect an authenticated request');
+            }
+            const bytes = await boundedBytes(response, response.ok ? maximum : Math.min(maximum, 1024 * 1024));
+            if (!response.ok) {
+                let value;
+                try {
+                    value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+                }
+                catch {
+                    throw new HttpError(response.status, 'invalid_response', 'The server returned an invalid error response');
+                }
+                const { error } = parseResponse(httpErrorSchema, value, response.status);
+                throw new HttpError(response.status, error.code, error.message, error.details);
+            }
+            const expectedStatus = method === 'POST' ? 201 : 200;
+            if (response.status !== expectedStatus)
+                throw new HttpError(response.status, 'invalid_response', `The server returned status ${response.status}, expected ${expectedStatus}`);
+            return await parse(response, bytes);
+        }
+        catch (error) {
+            if (error instanceof HttpError)
+                throw error;
+            if (controller.signal.aborted)
+                throw new HttpError(0, 'timeout', 'The server request timed out', {}, { cause: error });
+            throw new HttpError(0, 'network_error', 'The server request failed', {}, { cause: error });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    function json(path, method, schema, input) {
+        return request(path, method, (response, bytes) => {
+            if (response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/json')
+                throw new HttpError(response.status, 'invalid_response', 'The server did not return JSON');
+            let value;
+            try {
+                value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+            }
+            catch {
+                throw new HttpError(response.status, 'invalid_response', 'The server returned invalid JSON');
+            }
+            return parseResponse(schema, value, response.status);
+        }, input);
+    }
+    const client = {
+        identity: () => json('/identity', 'GET', identitySchema),
+        create(value) {
+            const input = createSchema.parse(value);
+            return json('/artifacts', 'POST', input.response === 'compact' ? compactArtifactReadSchema : artifactReadSchema, input);
+        },
+        list(value = {}) {
+            return json(`/artifacts${query(listSchema.parse(value))}`, 'GET', listResultSchema);
+        },
+        read(value) {
+            const { artifactId, ...parameters } = readSchema.parse(value);
+            return json(`/artifacts/${encodeURIComponent(artifactId)}${query(parameters)}`, 'GET', parameters.response === 'compact' ? compactArtifactReadSchema : artifactReadSchema);
+        },
+        update(value) {
+            const input = updateSchema.parse(value);
+            return json(`/artifacts/${encodeURIComponent(input.artifactId)}`, 'PUT', input.response === 'compact' ? compactArtifactReadSchema : artifactReadSchema, input);
+        },
+        history(value) {
+            const { artifactId, ...parameters } = historySchema.parse(value);
+            return json(`/artifacts/${encodeURIComponent(artifactId)}/history${query(parameters)}`, 'GET', parameters.response === 'summary' ? summaryHistoryResultSchema : historyResultSchema);
+        },
+        publish(value) {
+            const input = publishSchema.parse(value);
+            return json(`/artifacts/${encodeURIComponent(input.artifactId)}/publication`, 'PUT', publishResultSchema, input);
+        },
+        export(value) {
+            const input = exportSchema.parse(value);
+            return request(`/artifacts/${encodeURIComponent(input.artifactId)}/revisions/${encodeURIComponent(input.revisionId)}/export`, 'GET', async (response, bytes) => {
+                const disposition = response.headers.get('content-disposition');
+                const filename = /^attachment; filename="([A-Za-z0-9._-]+\.zip)"$/.exec(disposition ?? '')?.[1];
+                const digest = response.headers.get('x-artifact-sha256');
+                if (!filename || !digest || !/^[a-f0-9]{64}$/.test(digest) || response.headers.get('content-type')?.split(';')[0].trim() !== 'application/zip')
+                    throw new HttpError(response.status, 'invalid_response', 'The server returned invalid archive headers');
+                const actualDigest = Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', new Uint8Array(bytes))), (byte) => byte.toString(16).padStart(2, '0')).join('');
+                if (actualDigest !== digest)
+                    throw new HttpError(response.status, 'archive_digest_mismatch', 'The archive SHA-256 does not match its response header');
+                return { filename, mediaType: 'application/zip', bytes, sha256: digest };
+            }, undefined, maxArchiveBytes);
+        },
+    };
+    return client;
+}