@yargote/artifacts-client 0.1.0-beta.5 → 0.1.0-beta.6

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.5
+npm install @yargote/artifacts-client@0.1.0-beta.6
 ```
 
 ```ts
@@ -43,6 +43,9 @@ Every method makes one HTTP request. The client does not retry, follow redirects
 | `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`, `project` name or null | `{ artifactId, project }` |
 | `export(query)` | `artifactId`, `revisionId` | `{ filename, mediaType, bytes, sha256 }` |
 
@@ -50,6 +53,8 @@ Create, read, and update accept `response: 'compact'`. The returned revision con
 
 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`.
 
 `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.
@@ -60,7 +65,7 @@ Artifact reads and list items include `project`, a name or null. A project name
 
 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, publish, or move command before its first request. While the artifact exists, 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
 
@@ -69,3 +74,5 @@ The registry package contains compiled ESM JavaScript and declarations. Consumer
 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.5",
+  "version": "0.1.0-beta.6",
   "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.5",
+    "@yargote/artifacts-contracts": "0.1.0-beta.6",
     "zod": "4.6.5"
   },
   "publishConfig": {

package/src/index.d.ts

@@ -1,14 +1,20 @@
 import { z } from 'zod';
-import { createSchema, exportSchema, historySchema, listSchema, moveResultSchema, moveSchema, publishResultSchema, publishSchema, readSchema, type ArtifactRead, type UpdateInput } from '@yargote/artifacts-contracts';
+import { createSchema, exportSchema, historySchema, listSchema, listSharesSchema, moveResultSchema, moveSchema, publishResultSchema, publishSchema, readSchema, shareSchema, unshareSchema, type ArtifactRead, 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 MoveInput = z.input<typeof moveSchema>;
 export type MoveResult = z.infer<typeof moveResultSchema>;
@@ -62,6 +68,9 @@ 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>;
 }

package/src/index.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { artifactReadSchema, createSchema, exportSchema, historySchema, listSchema, moveResultSchema, moveSchema, publishResultSchema, publishSchema, readSchema, updateSchema } from '@yargote/artifacts-contracts';
+import { artifactReadSchema, createSchema, exportSchema, historySchema, listSchema, listSharesSchema, moveResultSchema, moveSchema, publishResultSchema, publishSchema, readSchema, 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 {
@@ -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;
@@ -157,13 +157,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');