@yargote/artifacts-client 0.1.0-beta.1 → 0.1.0-beta.10

package/README.md

@@ -3,7 +3,7 @@
 `@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
+npm install @yargote/artifacts-client@0.1.0-beta.10
 ```
 
 ```ts
@@ -23,7 +23,9 @@ const document = await client.read({ artifactId: 'artifact-id' });
 
 `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.
+`resource` is the exact canonical REST OAuth resource. Set it to the deployment's `API_URL` origin, such as `https://artifacts.example`, to use routes under `/v1`. Request access tokens for that same origin. MCP uses a separate `/mcp` audience. The client appends `/v1` to the supplied resource and does not remove or rewrite paths. Older deployments without `API_URL` retain their complete MCP resource and `/mcp/v1` routes.
+
+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.
 
@@ -36,18 +38,32 @@ Every method makes one HTTP request. The client does not retry, follow redirects
 | 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 |
+| `create(command)` | `requestId`, complete `snapshot`, optional `project`, `slug`, and `response` | Artifact receipt |
+| `list(query?)` | Optional `limit`, `cursor`, and `project` | Artifact summaries and `nextCursor` |
+| `projects()` | None | `{ items: [{ name, artifactCount }] }` |
+| `search(query)` | `query`, optional `project`, `limit`, and `cursor` | `{ items: SearchHit[], nextCursor }` |
+| `read(query)` | Exactly one of `artifactId` or `slug` with optional `project`, 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 |
+| `share(command)` | `requestId`, `artifactId`, `email`, optional `notify` and `requireNew: true` | Share receipt with optional notification disposition |
+| `listShares(query)` | `artifactId` | `{ items: Share[] }` |
+| `unshare(command)` | `requestId`, `artifactId`, `shareId` | `void` after an empty HTTP 204 |
+| `move(command)` | `requestId`, `artifactId`, and at least one of `project` (name or null) and `slug` (slug or null) | `{ artifactId, project }` |
 | `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.
 
+All sharing methods require `artifacts:publish` and artifact ownership. `share` trims and lowercases the email. The client places identifiers in encoded URL segments and sends `{ requestId, email }` plus any explicitly supplied `notify` or `requireNew` for share or `{ requestId }` for unshare. `unshare` resolves with `undefined` and requires no JSON content type on its empty response.
+
+Artifact reads and list items include `project`, a name or null. A project name matches an existing project regardless of letter case and keeps its stored spelling. `move` never creates a revision or changes the publication. `projects()` lists only projects that contain artifacts, ordered by name. Because response schemas are strict, this client requires a server that returns `project`. Version `0.1.0-beta.4` and earlier reject responses from such a server with `invalid_response`.
+
+Artifact reads and list items also include `slug`, a page name or null. `read({ project, slug })` calls `GET /lookup` and `read({ artifactId })` calls `GET /artifacts/:artifactId`. An omitted `project` reads the unfiled namespace. A used slug fails `create` with an `HttpError` whose code is `slug_conflict`, status 409, and whose details name the holder's `artifactId`. Version `0.1.0-beta.7` and earlier reject responses that include `slug` with `invalid_response`. `move` sets, changes, or clears the slug: an omitted field keeps its value and `null` clears it. A move into a used slug fails with the same `slug_conflict`. The move result is unchanged, so published clients keep parsing it. Read the artifact to see its new slug.
+
+`search({ query, project?, limit?, cursor? })` calls `GET /search` and searches the caller's owned Markdown and text artifacts at their head revision. Every whitespace-separated term must match, letter case and accents are ignored, and operators or punctuation in the query are treated as text, so input such as `"foo" OR NEAR(` never fails with a syntax error. HTML and design artifacts, older revisions, and artifacts shared with the caller are not searched. Items are `{ artifactId, project, slug, title, snippet, rank }`, ordered by `rank` and then `artifactId`. `rank` is the FTS5 `bm25` score, where lower is more relevant, and `snippet` is an excerpt with each match wrapped in `**`. Pass `nextCursor` as `cursor` for the next page. `limit` is 1 to 25 and defaults to 10.
+
 `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
@@ -56,10 +72,14 @@ All commands and JSON responses pass the strict domain schemas. An omitted mutat
 
 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.
+A caller that needs recovery retains the complete create, update, publish, move, share, or unshare command before its first request. While the artifact exists, retrying that exact command returns the original receipt or confirms unshare with another empty 204. Changing `response`, the snapshot, an expected version, or a sharing argument 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. Replaying a share after revocation returns its historical receipt without restoring access. A new unshare command for a removed share returns `not_found`.
 
 ## 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.
+
+Permanent deletion from the panel invalidates historical content-bearing receipts. An exact create, update, publish or move retry for a deleted artifact returns `not_found`; request identity remains reserved, so a changed command still returns `request_conflict` and an old create cannot recreate it. Live-session and scope checks still precede replay. This package exposes no deletion operation.
+
+`notify: true` requests one invitation attempt. The result adds `notification` with `status: "requested"`, or `status: "skipped"` and `reason: "disabled"` or `"rate_limited"`. A rate-limited result includes the next UTC day in `retryAt`. Access succeeds in each case. `requested` does not confirm delivery. Exact retries never send again. A fresh request can notify existing access. `requireNew: true` atomically rejects existing access with `conflict` and `details.reason: "share_exists"`. Plain and explicit-false results keep the five grant fields.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yargote/artifacts-client",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.10",
   "private": false,
   "type": "module",
   "description": "Typed HTTP client for the Artifacts REST API.",
@@ -26,7 +26,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@yargote/artifacts-contracts": "0.1.0-beta.1",
+    "@yargote/artifacts-contracts": "0.1.0-beta.10",
     "zod": "4.6.5"
   },
   "publishConfig": {

package/src/index.d.ts

@@ -1,15 +1,26 @@
 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 { createSchema, exportSchema, historySchema, listSchema, listSharesSchema, moveResultSchema, moveSchema, publishResultSchema, publishSchema, readSchema, searchSchema, shareSchema, unshareSchema, type ArtifactRead, type SearchResult, type Share, type ShareResult, type UpdateInput } from '@yargote/artifacts-contracts';
+import { historyResultSchema, listResultSchema, projectsResultSchema, 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 { ArtifactRead, Share, 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 ShareInput = z.input<typeof shareSchema>;
+export type UnshareInput = z.input<typeof unshareSchema>;
+export type ListSharesInput = z.input<typeof listSharesSchema>;
+export type ListSharesResult = {
+    items: Share[];
+};
 export type ListInput = z.input<typeof listSchema>;
+export type SearchInput = z.input<typeof searchSchema>;
+export type { SearchResult };
+export type MoveInput = z.input<typeof moveSchema>;
+export type MoveResult = z.infer<typeof moveResultSchema>;
+export type ProjectsResult = z.infer<typeof projectsResultSchema>;
 export type HistoryInput = z.input<typeof historySchema>;
 export type ExportInput = z.input<typeof exportSchema>;
 export type ArtifactArchive = {
@@ -36,6 +47,8 @@ export interface ArtifactHttpClient {
     }): Promise<ArtifactRead>;
     create(input: CreateInput): Promise<ArtifactRead | CompactArtifactRead>;
     list(input?: ListInput): Promise<z.infer<typeof listResultSchema>>;
+    projects(): Promise<ProjectsResult>;
+    search(input: SearchInput): Promise<SearchResult>;
     read(input: ReadInput & {
         response: 'compact';
     }): Promise<CompactArtifactRead>;
@@ -58,6 +71,10 @@ export interface ArtifactHttpClient {
     }): Promise<HistoryResult>;
     history(input: HistoryInput): Promise<HistoryResult | SummaryHistoryResult>;
     publish(input: PublishInput): Promise<z.infer<typeof publishResultSchema>>;
+    share(input: ShareInput): Promise<ShareResult>;
+    unshare(input: UnshareInput): Promise<void>;
+    listShares(input: ListSharesInput): Promise<ListSharesResult>;
+    move(input: MoveInput): Promise<MoveResult>;
     export(input: ExportInput): Promise<ArtifactArchive>;
 }
 export declare function createArtifactHttpClient(options: {

package/src/index.js

@@ -1,6 +1,6 @@
 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';
+import { artifactReadSchema, createSchema, exportSchema, historySchema, listSchema, listSharesSchema, moveResultSchema, moveSchema, publishResultSchema, publishSchema, readSchema, searchResultSchema, searchSchema, shareCommandResultSchema, shareResultSchema, shareSchema, unshareSchema, updateSchema } from '@yargote/artifacts-contracts';
+import { compactArtifactReadSchema, historyResultSchema, httpErrorSchema, identitySchema, listResultSchema, projectsResultSchema, restBase, summaryHistoryResultSchema } from '@yargote/artifacts-contracts/http';
 export { prepareArtifactEdit } from '@yargote/artifacts-contracts/workflow';
 export class HttpError extends Error {
     status;
@@ -16,6 +16,7 @@ export class HttpError extends Error {
 }
 const maxJsonBytes = 64 * 1024 * 1024;
 const maxArchiveBytes = 8 * 1024 * 1024;
+const listSharesResultSchema = z.strictObject({ items: z.array(shareResultSchema) });
 async function boundedBytes(response, maximum) {
     const length = response.headers.get('content-length');
     if (length !== null && (!/^\d+$/.test(length) || Number(length) > maximum)) {
@@ -71,7 +72,7 @@ export function createArtifactHttpClient(options) {
     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) {
+    async function request(path, method, expectedStatus, 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');
@@ -101,7 +102,6 @@ export function createArtifactHttpClient(options) {
                 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);
@@ -118,7 +118,7 @@ export function createArtifactHttpClient(options) {
         }
     }
     function json(path, method, schema, input) {
-        return request(path, method, (response, bytes) => {
+        return request(path, method, method === 'POST' ? 201 : 200, (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;
@@ -140,9 +140,13 @@ export function createArtifactHttpClient(options) {
         list(value = {}) {
             return json(`/artifacts${query(listSchema.parse(value))}`, 'GET', listResultSchema);
         },
+        projects: () => json('/projects', 'GET', projectsResultSchema),
+        search(value) {
+            return json(`/search${query(searchSchema.parse(value))}`, 'GET', searchResultSchema);
+        },
         read(value) {
             const { artifactId, ...parameters } = readSchema.parse(value);
-            return json(`/artifacts/${encodeURIComponent(artifactId)}${query(parameters)}`, 'GET', parameters.response === 'compact' ? compactArtifactReadSchema : artifactReadSchema);
+            return json(`${artifactId === undefined ? '/lookup' : `/artifacts/${encodeURIComponent(artifactId)}`}${query(parameters)}`, 'GET', parameters.response === 'compact' ? compactArtifactReadSchema : artifactReadSchema);
         },
         update(value) {
             const input = updateSchema.parse(value);
@@ -156,9 +160,28 @@ export function createArtifactHttpClient(options) {
             const input = publishSchema.parse(value);
             return json(`/artifacts/${encodeURIComponent(input.artifactId)}/publication`, 'PUT', publishResultSchema, input);
         },
+        share(value) {
+            const { artifactId, ...input } = shareSchema.parse(value);
+            return json(`/artifacts/${encodeURIComponent(artifactId)}/shares`, 'POST', shareCommandResultSchema, input);
+        },
+        listShares(value) {
+            const { artifactId } = listSharesSchema.parse(value);
+            return json(`/artifacts/${encodeURIComponent(artifactId)}/shares`, 'GET', listSharesResultSchema);
+        },
+        unshare(value) {
+            const { artifactId, shareId, ...input } = unshareSchema.parse(value);
+            return request(`/artifacts/${encodeURIComponent(artifactId)}/shares/${encodeURIComponent(shareId)}`, 'DELETE', 204, (response, bytes) => {
+                if (bytes.byteLength !== 0)
+                    throw new HttpError(response.status, 'invalid_response', 'The server returned a nonempty response');
+            }, input);
+        },
+        move(value) {
+            const input = moveSchema.parse(value);
+            return json(`/artifacts/${encodeURIComponent(input.artifactId)}/project`, 'PUT', moveResultSchema, input);
+        },
         export(value) {
             const input = exportSchema.parse(value);
-            return request(`/artifacts/${encodeURIComponent(input.artifactId)}/revisions/${encodeURIComponent(input.revisionId)}/export`, 'GET', async (response, bytes) => {
+            return request(`/artifacts/${encodeURIComponent(input.artifactId)}/revisions/${encodeURIComponent(input.revisionId)}/export`, 'GET', 200, 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');