@hivemagnus/hivemem-sdk 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to `@hivemagnus/hivemem-sdk`.
+
+## [1.1.0] - 2026-11-12
+
+### Added
+
+- `createWorkspace(workspaceId, options)` calls `POST /v1/workspaces` and returns the
+  `WorkspaceRecord`. It is idempotent: an existing workspace the caller can read is returned
+  unchanged. New `WorkspaceRecord`, `WorkspaceMember`, `WorkspacePolicy` and
+  `WorkspaceCreateOptions` types.
+- `tokenProvider` option for short-lived credentials such as Oathweave service tokens. It is
+  called before each request and, after a 401, called again with `forceRefresh: true` and the
+  request retried once. A static `token` keeps working unchanged.
+- `headers` option: extra headers on every request, static or from a function called per
+  request, for example to propagate `x-request-id` and `traceparent`. They cannot replace
+  `Accept`, `Content-Type` or `Authorization`.
+
+### Security
+
+- Every request is sent with `redirect: "error"`, so a redirect can no longer carry the bearer
+  token to another origin.
+
+## [1.0.3]
+
+- Earlier releases are described in the HiveMem repository changelog.

package/README.md

@@ -1,10 +1,11 @@
 # @hivemagnus/hivemem-sdk
 
-TypeScript client for [HiveMem](https://github.com/ChefTaco/hive/tree/main/services/hive-mem), the shared long-term memory service for AI agents. It wraps the HiveMem REST API with typed helpers for memories, search, sessions, prompt context, peer cards, conclusions, queue operations, and webhooks.
+TypeScript client for [HiveMem](https://github.com/ChefTaco/HiveMem), the shared long-term memory service for AI agents. It wraps the HiveMem REST API with typed helpers for memories, search, sessions, prompt context, peer cards, conclusions, queue operations, and webhooks.
 
 - Zero runtime dependencies; uses the platform `fetch` (Node.js 18.17+, Deno, Bun, browsers, edge runtimes).
 - ESM-only, with bundled type declarations.
-- Retries 5xx responses, supports request timeouts, request IDs, and token refresh hooks.
+- Retries 5xx responses, supports request timeouts, request IDs, extra headers, and token providers that refresh on 401.
+- Never follows redirects (`redirect: "error"`), so the bearer token stays with the configured origin.
 
 ## Install
 
@@ -12,7 +13,7 @@ TypeScript client for [HiveMem](https://github.com/ChefTaco/hive/tree/main/servi
 npm install @hivemagnus/hivemem-sdk
 ```
 
-You need a running HiveMem server and an agent token. See the [HiveMem README](https://github.com/ChefTaco/hive/tree/main/services/hive-mem#readme) for how to run the server and register an agent.
+You need a running HiveMem server and an agent token. See the [HiveMem README](https://github.com/ChefTaco/HiveMem#readme) for how to run the server and register an agent.
 
 ## Quick start
 
@@ -53,10 +54,30 @@ const messages = context.toOpenAI(); // or context.toAnthropic()
 | `fetchImpl` | | global `fetch` |
 | `requestIdProvider` | | sends `X-Request-ID` when set |
 | `authRefresh` | | called before each attempt; a returned token replaces the current one |
+| `tokenProvider` | | `({ forceRefresh }) => token`; called before each request, and again with `forceRefresh: true` after a 401, when the request is retried once |
+| `headers` | | extra headers on every request, or a function returning them per request; cannot replace `Accept`, `Content-Type` or `Authorization` |
 | `onRequest` / `onResponse` | | observability hooks |
 
 Explicit constructor options win over environment variables. Environment variables are only read where `process.env` exists.
 
+### Service tokens and request propagation
+
+A product calling HiveMem with a short-lived Oathweave service token passes a `tokenProvider`
+instead of a static `token`. Cache the token in the provider and fetch a new one when
+`forceRefresh` is true (HiveMem answered 401) or the cached one is near expiry. Use `headers` to
+forward the caller's request ID and trace context:
+
+```ts
+const hivemem = new HiveMem({
+  baseUrl: "https://memory.example.com",
+  tokenProvider: ({ forceRefresh }) => serviceTokens.get({ forceRefresh }),
+  headers: () => ({ "x-request-id": currentRequestId(), traceparent: currentTraceparent() }),
+});
+
+// Create the workspace your agents join; returns the existing one if it is already there.
+const workspace = await hivemem.createWorkspace("team-alpha", { title: "Team Alpha" });
+```
+
 ## Common operations
 
 ```ts
@@ -115,6 +136,10 @@ const ok = await verifyHiveMemWebhook({
 });
 ```
 
+## Releasing
+
+Maintainers: see [RELEASING.md](https://github.com/ChefTaco/HiveMem/blob/main/sdks/typescript/RELEASING.md). In short, bump the version, push a tag `sdk-vX.Y.Z`, and approve the publish run.
+
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE).

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { ContextPackage } from "./context.js";
-import type { ConclusionPage, ConclusionRecord, HiveMemOptions, KnowledgeSourceSyncResponse, MemoryRecord, PeerCardResponse, QueueJobRecord, QueueStatusResponse, SearchResponse, SessionRecord, WebhookEndpoint } from "./types.js";
+import type { ConclusionPage, ConclusionRecord, HiveMemOptions, KnowledgeSourceSyncResponse, MemoryRecord, PeerCardResponse, QueueJobRecord, QueueStatusResponse, SearchResponse, SessionRecord, WebhookEndpoint, WorkspaceCreateOptions, WorkspaceRecord } from "./types.js";
 export declare class HiveMem {
     readonly baseUrl: string;
     token?: string;
@@ -9,12 +9,20 @@ export declare class HiveMem {
     private readonly fetchImpl;
     private readonly requestIdProvider?;
     private readonly authRefresh?;
+    private readonly tokenProvider?;
+    private readonly extraHeaders?;
     private readonly onRequest?;
     private readonly onResponse?;
     constructor(options?: HiveMemOptions);
     private url;
     private request;
     health(): Promise<Record<string, unknown>>;
+    /**
+     * Create a workspace, owned by the caller (`POST /v1/workspaces`, scope `workspaces:write`).
+     * Idempotent: when the workspace already exists and the caller can read it, the server returns
+     * it unchanged. An archived workspace ID is a 409.
+     */
+    createWorkspace(workspaceId: string, options?: WorkspaceCreateOptions): Promise<WorkspaceRecord>;
     getMemory(memoryId: string, options?: {
         includeHistory?: boolean;
     }): Promise<MemoryRecord>;

package/dist/client.js

@@ -13,6 +13,8 @@ export class HiveMem {
     fetchImpl;
     requestIdProvider;
     authRefresh;
+    tokenProvider;
+    extraHeaders;
     onRequest;
     onResponse;
     constructor(options = {}) {
@@ -24,6 +26,8 @@ export class HiveMem {
         this.fetchImpl = options.fetchImpl ?? fetch;
         this.requestIdProvider = options.requestIdProvider;
         this.authRefresh = options.authRefresh;
+        this.tokenProvider = options.tokenProvider;
+        this.extraHeaders = options.headers;
         this.onRequest = options.onRequest;
         this.onResponse = options.onResponse;
     }
@@ -36,14 +40,23 @@ export class HiveMem {
             if (value !== undefined && value !== null)
                 url.searchParams.set(key, String(value));
         }
-        const headers = new Headers(init.headers);
+        const extra = typeof this.extraHeaders === "function" ? await this.extraHeaders() : this.extraHeaders;
+        const headers = new Headers(extra);
+        new Headers(init.headers).forEach((value, key) => headers.set(key, value));
         headers.set("Accept", "application/json");
         if (init.body && !headers.has("Content-Type"))
             headers.set("Content-Type", "application/json");
         if (this.requestIdProvider)
             headers.set("X-Request-ID", this.requestIdProvider());
+        headers.delete("Authorization");
+        if (this.tokenProvider) {
+            const provided = await this.tokenProvider({ forceRefresh: false });
+            if (provided)
+                this.token = provided;
+        }
         if (this.token)
             headers.set("Authorization", `Bearer ${this.token}`);
+        let reauthorized = false;
         for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
             const refreshed = await this.authRefresh?.();
             if (refreshed) {
@@ -53,10 +66,22 @@ export class HiveMem {
             const controller = new AbortController();
             const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
             try {
-                const requestInit = { ...init, method, headers, signal: controller.signal };
+                const requestInit = { ...init, method, headers, signal: controller.signal, redirect: "error" };
                 this.onRequest?.(method, String(url), requestInit);
                 const response = await this.fetchImpl(url, requestInit);
                 this.onResponse?.(response);
+                if (response.status === 401 && this.tokenProvider && !reauthorized) {
+                    // A service token may have expired or been revoked: fetch a fresh one and retry once.
+                    reauthorized = true;
+                    const fresh = await this.tokenProvider({ forceRefresh: true });
+                    if (fresh) {
+                        await response.body?.cancel().catch(() => undefined);
+                        this.token = fresh;
+                        headers.set("Authorization", `Bearer ${this.token}`);
+                        attempt -= 1;
+                        continue;
+                    }
+                }
                 if (response.status >= 500 && attempt < this.maxRetries)
                     continue;
                 if (!response.ok) {
@@ -85,6 +110,14 @@ export class HiveMem {
     health() {
         return this.request("GET", "/v1/health");
     }
+    /**
+     * Create a workspace, owned by the caller (`POST /v1/workspaces`, scope `workspaces:write`).
+     * Idempotent: when the workspace already exists and the caller can read it, the server returns
+     * it unchanged. An archived workspace ID is a 409.
+     */
+    createWorkspace(workspaceId, options = {}) {
+        return this.request("POST", "/v1/workspaces", { body: JSON.stringify({ ...options, workspace_id: workspaceId }) });
+    }
     getMemory(memoryId, options = {}) {
         const params = options.includeHistory ? { include_history: true } : {};
         return this.request("GET", `/v1/memories/${encodeURIComponent(memoryId)}`, {}, params);

package/dist/types.d.ts

@@ -10,9 +10,75 @@ export interface HiveMemOptions {
     fetchImpl?: typeof fetch;
     requestIdProvider?: () => string;
     authRefresh?: () => string | undefined | Promise<string | undefined>;
+    /**
+     * Supplies the bearer token, for example a short-lived Oathweave service token. Called before
+     * each request with `forceRefresh: false`; after a 401 it is called again with
+     * `forceRefresh: true` and the request is retried once with the token it returns. Returning
+     * `undefined` falls back to `token`.
+     */
+    tokenProvider?: TokenProvider;
+    /**
+     * Extra headers sent on every request, such as `x-request-id` or `traceparent` taken from the
+     * caller's request context. A function is called once per request. They never replace the
+     * client's own `Accept` or `Content-Type` headers, and `Authorization` comes only from `token`,
+     * `tokenProvider` or `authRefresh`.
+     */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
     onRequest?: (method: string, url: string, init: RequestInit) => void;
     onResponse?: (response: Response) => void;
 }
+export interface TokenProviderContext {
+    /** True after the server answered 401: the cached token must not be reused. */
+    forceRefresh: boolean;
+}
+export type TokenProvider = (context: TokenProviderContext) => string | undefined | Promise<string | undefined>;
+export type WorkspaceRole = "viewer" | "member" | "admin" | "owner";
+export interface WorkspaceMember {
+    agent_id: string;
+    role: WorkspaceRole;
+    scopes: string[];
+    added_by: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface WorkspaceSanitizationPolicy {
+    mode: "warn" | "redact" | "reject" | null;
+    detect_pii: boolean | null;
+    detect_secrets: boolean | null;
+    deny_regexes: string[];
+}
+export interface WorkspacePolicy {
+    retention_days: number | null;
+    allowed_scopes: string[];
+    reasoning_provider: string | null;
+    consolidation_cadence_seconds: number | null;
+    webhooks_enabled: boolean;
+    sanitization: WorkspaceSanitizationPolicy;
+    agent_overrides: Record<string, Record<string, unknown>>;
+    session_overrides: Record<string, Record<string, unknown>>;
+}
+export interface WorkspaceRecord {
+    workspace_id: string;
+    owner_agent_id: string;
+    title: string | null;
+    description: string | null;
+    metadata: Record<string, unknown>;
+    policy: WorkspacePolicy;
+    members: WorkspaceMember[];
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+}
+/** Optional fields of `POST /v1/workspaces`; `workspace_id` is the method's first argument. */
+export interface WorkspaceCreateOptions {
+    title?: string | null;
+    description?: string | null;
+    metadata?: Record<string, unknown>;
+    policy?: Partial<Omit<WorkspacePolicy, "sanitization">> & {
+        sanitization?: Partial<WorkspaceSanitizationPolicy>;
+    };
+    members?: Array<Pick<WorkspaceMember, "agent_id"> & Partial<Pick<WorkspaceMember, "role" | "scopes">>>;
+}
 export interface MemoryRecord {
     id: string;
     agent_id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemagnus/hivemem-sdk",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "TypeScript client for HiveMem, the shared long-term memory service for AI agents",
   "keywords": [
     "hivemem",
@@ -13,14 +13,14 @@
     "context",
     "sdk"
   ],
-  "homepage": "https://github.com/ChefTaco/hive/tree/main/services/hive-mem/sdks/typescript#readme",
+  "homepage": "https://github.com/ChefTaco/HiveMem/tree/main/sdks/typescript#readme",
   "bugs": {
-    "url": "https://github.com/ChefTaco/hive/issues"
+    "url": "https://github.com/ChefTaco/HiveMem/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ChefTaco/hive.git",
-    "directory": "services/hive-mem/sdks/typescript"
+    "url": "git+https://github.com/ChefTaco/HiveMem.git",
+    "directory": "sdks/typescript"
   },
   "license": "Apache-2.0",
   "author": "ChefTaco",
@@ -38,6 +38,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "sideEffects": false,
@@ -51,9 +52,11 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "node --test test/*.test.mjs",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run build && npm test",
+    "pack:check": "node scripts/check-package.mjs"
   },
   "devDependencies": {
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "yaml": "2.9.1"
   }
 }