@ai-agent-huddle/once 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Global Talent Leaders LTD
+
+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,30 @@
-# Temporary Holding Version
+# @ai-agent-huddle/once
 
-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.
+Typed, dependency-free HTTP client for [ONCE by AI Agent Huddle](https://once.aiagenthuddle.com/docs.html). Node.js 22+, ESM. This package contains public client code; it contains no service implementation.
+
+```sh
+npm install @ai-agent-huddle/once
+```
+
+```js
+import { OnceClient, HuddleError } from '@ai-agent-huddle/once';
+
+const once = new OnceClient({ apiKey: process.env.ONCE_API_KEY });
+const input = { provider: 'stripe', action: 'create_payment_intent',
+  parameters: { amount: 100, currency: 'gbp' } };
+const credentials = { stripeTestKey: process.env.STRIPE_TEST_KEY };
+// Persist this key before dispatch; always reuse identical inputs for this operation.
+const operation = await once.create(process.env.ONCE_OPERATION_KEY, input, credentials);
+const recorded = await once.get(operation.operation_id);
+console.log(recorded.status);
+```
+
+The Stripe action creates an **unconfirmed test PaymentIntent**; it never captures a live payment. Only sandbox secret keys starting `sk_test_` are accepted. GitHub supports `create_issue` with `{ title, body }` and `{ githubToken, githubRepository: 'owner/repository' }`; it creates a real issue. Both title and body must be strings; use an empty body string if needed. Use a repository-restricted fine-grained token with Issues read/write. There is no arbitrary action or universal exactly-once guarantee.
+
+Methods: `create(key, input, credentials, options?)`, `get(id, options?)`, `reconcile(id, credentials, options?)`, `retry(id, credentials, options?)`. Reconciliation inspects provider evidence. `retry` is an explicit new attempt, permitted only when the recorded provider evidence establishes safety. `UNKNOWN`, `AMBIGUOUS`, `CREATED` or `EXECUTING` requires inspection; never blindly redispatch. A replay returning the same ID is not proof the provider effect succeeded. Preserve the key, inputs and returned ID durably. See the [recovery guide](https://once.aiagenthuddle.com/guides/recovering-uncertain-actions.html).
+
+Errors are `HuddleError` with a safe `code`, optional HTTP `status` and numeric `retryAfterSeconds`. Raw server bodies, network errors and credentials are omitted. Timeouts, aborts and network failures leave mutation outcomes uncertain; the SDK never retries. HTTP 409 is an error. Inspect the existing operation before deciding a next action.
+
+Client options: `{ apiKey, timeoutMs?: 30000, baseUrl?, fetch? }`. Request options: `{ signal?, timeoutMs? }`. Timeouts range from 1 to 120000 milliseconds and apply through response reading. HTTPS origins only; no paths, query, fragment or URL credentials. Redirects are rejected. A custom origin or fetch implementation receives your credentials, so use only one you trust. Keep clients and provider keys in server code, never a browser bundle. `get` sends only your ONCE key; provider credentials are scoped to each explicit provider method call. Avoid logging input objects, fetch headers or successful provider references if sensitive.
+
+[Runnable source examples](https://github.com/londoncoding/ai-agent-huddle-examples/tree/main/sdk-examples) · [Support and service information](https://once.aiagenthuddle.com/service.html) · MIT licence.

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { HuddleError } from './options.js';
+export type { ClientOptions, RequestOptions, ErrorCode } from './options.js';
+import type { ClientOptions, RequestOptions } from './options.js';
+export type OperationStatus = 'CREATED' | 'EXECUTING' | 'COMMITTED' | 'NOT_COMMITTED' | 'UNKNOWN' | 'PROVEN_COMMITTED' | 'PROVEN_NOT_COMMITTED' | 'AMBIGUOUS';
+export interface Operation { operation_id: string; status: OperationStatus; retry_safe: boolean; provider_reference?: string }
+export interface Reconciliation extends Operation { previous_status: OperationStatus; evidence: { reason: string } }
+export type GitHubCredentials = { githubToken: string; githubRepository: string; stripeTestKey?: never };
+export type StripeTestCredentials = { stripeTestKey: string; githubToken?: never; githubRepository?: never };
+export type ProviderCredentials = GitHubCredentials | StripeTestCredentials;
+export interface GitHubIssue { provider: 'github'; action: 'create_issue'; parameters: { title: string; body: string }; metadata?: Record<string, unknown> }
+export interface StripeTestPaymentIntent { provider: 'stripe'; action: 'create_payment_intent'; parameters: { amount: number; currency: string }; metadata?: Record<string, unknown> }
+export declare class OnceClient {
+  constructor(options: ClientOptions);
+  create(key: string, input: GitHubIssue, provider: GitHubCredentials, options?: RequestOptions): Promise<Operation>;
+  create(key: string, input: StripeTestPaymentIntent, provider: StripeTestCredentials, options?: RequestOptions): Promise<Operation>;
+  get(id: string, options?: RequestOptions): Promise<Operation>;
+  reconcile(id: string, provider: ProviderCredentials, options?: RequestOptions): Promise<Reconciliation>;
+  retry(id: string, provider: ProviderCredentials, options?: RequestOptions): Promise<Operation>;
+}

package/dist/index.js

@@ -0,0 +1,52 @@
+import { Transport, text, segment, record, invalid, protocol, uuid, responseText } from './transport.js';
+export { HuddleError } from './transport.js';
+const STATES = new Set(['CREATED', 'EXECUTING', 'COMMITTED', 'NOT_COMMITTED', 'UNKNOWN', 'PROVEN_COMMITTED', 'PROVEN_NOT_COMMITTED', 'AMBIGUOUS']);
+function operation(value) {
+  protocol(STATES.has(value.status) && typeof value.retry_safe === 'boolean');
+  const result = { operation_id: uuid(value.operation_id), status: value.status, retry_safe: value.retry_safe };
+  if (value.provider_reference !== undefined) result.provider_reference = responseText(value.provider_reference);
+  return result;
+}
+function credentials(value) {
+  if (!record(value)) invalid();
+  if (value.githubToken !== undefined && value.stripeTestKey !== undefined) invalid();
+  if (value.githubToken !== undefined) {
+    text(value.githubToken, 4096); text(value.githubRepository, 256);
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value.githubRepository)) invalid();
+    return { 'Once-GitHub-Token': value.githubToken, 'Once-GitHub-Repository': value.githubRepository };
+  }
+  if (value.stripeTestKey !== undefined) {
+    text(value.stripeTestKey, 4096);
+    if (!/^sk_test_[A-Za-z0-9]+$/.test(value.stripeTestKey)) invalid();
+    return { 'Once-Stripe-Test-Key': value.stripeTestKey };
+  }
+  invalid();
+}
+export class OnceClient {
+  #transport;
+  constructor(options) { this.#transport = new Transport('https://once.aiagenthuddle.com', options); }
+  async create(key, input, provider, options) {
+    text(key, 200);
+    if (/\s/.test(key) || !record(input) || !record(input.parameters)) invalid();
+    if (!((input.provider === 'github' && input.action === 'create_issue' && provider?.githubToken !== undefined) ||
+      (input.provider === 'stripe' && input.action === 'create_payment_intent' && provider?.stripeTestKey !== undefined))) invalid();
+    if (input.provider === 'github' && (typeof input.parameters.title !== 'string' || typeof input.parameters.body !== 'string')) invalid();
+    const headers = { ...credentials(provider), 'Idempotency-Key': key };
+    const body = { provider: input.provider, action: input.action, parameters: input.parameters };
+    if (input.metadata !== undefined) { if (!record(input.metadata)) invalid(); body.metadata = input.metadata; }
+    return operation(await this.#transport.request('/v1/operations', 'POST', body, headers, options));
+  }
+  async get(id, options) { return operation(await this.#transport.request(`/v1/operations/${segment(id)}`, 'GET', undefined, {}, options)); }
+  async reconcile(id, provider, options) {
+    const value = await this.#transport.request(`/v1/operations/${segment(id)}/reconcile`, 'POST', {}, credentials(provider), options);
+    const result = operation(value);
+    protocol(STATES.has(value.previous_status) && record(value.evidence));
+    // Evidence descriptions are protocol codes; never relay arbitrary server text.
+    protocol(typeof value.evidence.reason === 'string' && /^[A-Z][A-Z0-9_]{0,127}$/.test(value.evidence.reason));
+    return { ...result, previous_status: value.previous_status, evidence: { reason: value.evidence.reason } };
+  }
+  /** Explicit new attempt. Call only after provider evidence establishes retry safety. */
+  async retry(id, provider, options) {
+    return operation(await this.#transport.request(`/v1/operations/${segment(id)}/retry`, 'POST', {}, credentials(provider), options));
+  }
+}

package/dist/options.d.ts

@@ -0,0 +1,21 @@
+export type ErrorCode = 'INVALID_ARGUMENT' | 'INVALID_RESPONSE' | 'HTTP_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'ABORTED';
+export declare class HuddleError extends Error {
+  readonly code: ErrorCode;
+  readonly status?: number;
+  readonly retryAfterSeconds?: number;
+}
+export interface ClientOptions {
+  /** Project API key. Keep this client on the server. */
+  apiKey: string;
+  /** HTTPS origin only. Changing this sends credentials to that origin. */
+  baseUrl?: string;
+  /** Defaults to 30000; integer between 1 and 120000. */
+  timeoutMs?: number;
+  /** Trusted fetch implementation; receives credentials. */
+  fetch?: typeof globalThis.fetch;
+}
+export interface RequestOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+export interface Observation { request_id?: string; process_session_id?: string }

package/dist/transport.js

@@ -0,0 +1,119 @@
+// Public HTTP transport only. No service implementation or storage access.
+const MAX_RESPONSE_BYTES = 1024 * 1024;
+export class HuddleError extends Error {
+  constructor(code, status, retryAfterSeconds) {
+    super(status === undefined ? `AI Agent Huddle ${code}` : `AI Agent Huddle HTTP ${status}`);
+    this.name = 'HuddleError';
+    this.code = code;
+    if (status !== undefined) this.status = status;
+    if (retryAfterSeconds !== undefined) this.retryAfterSeconds = retryAfterSeconds;
+  }
+}
+export function invalid() { throw new HuddleError('INVALID_ARGUMENT'); }
+export function text(value, max = 512) {
+  if (typeof value !== 'string' || !value.trim() || value.length > max || /[\u0000-\u001f\u007f]/.test(value)) invalid();
+  return value;
+}
+export function integer(value, min, max) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) invalid();
+  return value;
+}
+export function segment(value) {
+  text(value);
+  // Dot segments are normalized by URL/fetch even when percent encoded.
+  if (value === '.' || value === '..') invalid();
+  try { return encodeURIComponent(value); } catch { invalid(); }
+}
+export function record(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+export function protocol(condition) { if (!condition) throw new HuddleError('INVALID_RESPONSE'); }
+export function uuid(value) {
+  protocol(typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value));
+  return value;
+}
+export function responseText(value, max = 512) {
+  protocol(typeof value === 'string' && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value));
+  return value;
+}
+export function nullableText(value) { return value === null ? null : responseText(value); }
+export function observation(value = {}) {
+  if (!record(value)) invalid();
+  const output = {};
+  for (const field of ['request_id', 'process_session_id']) {
+    if (value[field] !== undefined) {
+      text(value[field], 36);
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value[field])) invalid();
+      output[field] = value[field];
+    }
+  }
+  return output;
+}
+function timeout(value) { return integer(value, 1, 120000); }
+export class Transport {
+  #origin; #apiKey; #fetch; #timeoutMs;
+  constructor(defaultOrigin, options) {
+    if (!record(options)) invalid();
+    text(options.apiKey, 4096);
+    let endpoint;
+    try { endpoint = new URL(options.baseUrl ?? defaultOrigin); } catch { invalid(); }
+    if (endpoint.protocol !== 'https:' || endpoint.username || endpoint.password || endpoint.search || endpoint.hash || endpoint.pathname !== '/') invalid();
+    this.#origin = endpoint.origin;
+    this.#apiKey = options.apiKey;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+    if (typeof this.#fetch !== 'function') invalid();
+    this.#timeoutMs = timeout(options.timeoutMs ?? 30000);
+  }
+  async request(path, method, body, providerHeaders = {}, options = {}) {
+    if (!record(options)) invalid();
+    const timeoutSignal = AbortSignal.timeout(timeout(options.timeoutMs ?? this.#timeoutMs));
+    let signal = timeoutSignal;
+    if (options.signal !== undefined) {
+      if (!(options.signal instanceof AbortSignal)) invalid();
+      signal = AbortSignal.any([signal, options.signal]);
+    }
+    if (signal.aborted) throw new HuddleError(timeoutSignal.aborted ? 'TIMEOUT' : 'ABORTED');
+    let serialized;
+    try { serialized = body === undefined ? undefined : JSON.stringify(body); } catch { invalid(); }
+    const headers = { Authorization: `Bearer ${this.#apiKey}`, Accept: 'application/json', ...providerHeaders };
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    let response;
+    try {
+      response = await this.#fetch(this.#origin + path, {
+        method, headers, body: serialized, signal, redirect: 'error', credentials: 'omit', cache: 'no-store'
+      });
+    } catch {
+      throw new HuddleError(timeoutSignal.aborted ? 'TIMEOUT' : signal.aborted ? 'ABORTED' : 'NETWORK_ERROR');
+    }
+    protocol(Number.isInteger(response.status) && response.status >= 100 && response.status <= 599);
+    const retry = response.headers.get('retry-after');
+    const retryAfterSeconds = retry && /^\d{1,6}$/.test(retry) ? Number(retry) : undefined;
+    // A denial is a typed acquire result; all other non-2xx responses stay opaque.
+    if (!response.ok && !(method === 'POST' && path === '/v1/leases' && response.status === 409)) {
+      try { await response.body?.cancel(); } catch { /* Do not expose stream errors. */ }
+      throw new HuddleError('HTTP_ERROR', response.status, retryAfterSeconds);
+    }
+    protocol(response.headers.get('content-type')?.toLowerCase().includes('application/json'));
+    let value;
+    try {
+      const reader = response.body?.getReader();
+      if (!reader) throw new Error();
+      const chunks = []; let bytes = 0;
+      try {
+        while (true) {
+          const { value: chunk, done } = await reader.read();
+          if (done) break;
+          bytes += chunk.byteLength;
+          if (bytes > MAX_RESPONSE_BYTES) { await reader.cancel(); throw new Error(); }
+          chunks.push(chunk);
+        }
+      } finally { reader.releaseLock(); }
+      const content = new Uint8Array(bytes); let offset = 0;
+      for (const chunk of chunks) { content.set(chunk, offset); offset += chunk.byteLength; }
+      value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(content));
+    } catch {
+      throw new HuddleError(timeoutSignal.aborted ? 'TIMEOUT' : signal.aborted ? 'ABORTED' : 'INVALID_RESPONSE');
+    }
+    protocol(record(value));
+    if (!response.ok && value.status !== 'DENIED') throw new HuddleError('HTTP_ERROR', response.status, retryAfterSeconds);
+    return value;
+  }
+}

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "@ai-agent-huddle/once",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Typed HTTP client for AI Agent Huddle ONCE operation recovery",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=22" },
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/londoncoding/ai-agent-huddle-examples.git", "directory": "packages/once" },
+  "homepage": "https://once.aiagenthuddle.com/docs.html",
+  "bugs": { "url": "https://github.com/londoncoding/ai-agent-huddle-examples/issues" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "keywords": ["ai-agent-huddle", "agents", "idempotency", "recovery", "sdk"]
+}