@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/packages/identity/tests/portable-identity-architecture.test.mjs

@@ -0,0 +1,157 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { createLocalSqliteDatabase } from '../../../src/local/sqlite.js';
+import { IDENTITY_ROUTE_IDS } from '../src/contracts/route-ids.js';
+import {
+  createRouteRegistry,
+  projectionFromAppManifest,
+} from '../src/contracts/route-projection.js';
+import { IdentityRoutingError } from '../src/contracts/identity-store.js';
+import { resolvePostAuthDestination } from '../src/server/post-auth.js';
+import {
+  applySqliteIdentityMigrations,
+  createSqliteIdentityAdapter,
+} from '../src/adapters/sqlite/index.js';
+import { createIdentityService } from '../src/server/identity-service.js';
+import { verifyAppPackage, verifyAppAuthContract } from '../src/app/verify-app.js';
+import { SESSION_POLICY } from '../src/core/session-policy.js';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+const LOCAL_STUDIO = path.join(REPO, 'apps/local-studio');
+
+describe('IDENTITY_ROUTE_IDS (portable semantics)', () => {
+  it('exports semantic IDs only — no host paths', () => {
+    assert.equal(IDENTITY_ROUTE_IDS.LOGIN, 'identity.login');
+    assert.equal(IDENTITY_ROUTE_IDS.APP_AUTHENTICATED, 'app.authenticated');
+    assert.equal(IDENTITY_ROUTE_IDS.OAUTH_CALLBACK, 'identity.oauth.callback');
+    for (const v of Object.values(IDENTITY_ROUTE_IDS)) {
+      assert.equal(v.includes('/'), false, `path leaked into portable ID: ${v}`);
+    }
+  });
+});
+
+describe('route projection + fail-closed post-auth', () => {
+  const manifest = JSON.parse(
+    fs.readFileSync(path.join(LOCAL_STUDIO, 'agentsam.app.json'), 'utf8'),
+  );
+  const projection = projectionFromAppManifest(manifest);
+  const routeRegistry = createRouteRegistry([projection]);
+  const app = { id: 'local-studio' };
+
+  it('host projection maps identity.login → /auth/login', () => {
+    assert.equal(routeRegistry.resolve('local-studio', IDENTITY_ROUTE_IDS.LOGIN), '/auth/login');
+    assert.equal(
+      routeRegistry.resolve('local-studio', IDENTITY_ROUTE_IDS.APP_AUTHENTICATED),
+      '/agentsam',
+    );
+  });
+
+  it('resumes validated return_to', () => {
+    assert.equal(
+      resolvePostAuthDestination({
+        transaction: { app_id: 'local-studio', return_to: '/projects/abc' },
+        app,
+        routeRegistry,
+      }),
+      '/projects/abc',
+    );
+  });
+
+  it('falls back to authenticated entry — never /', () => {
+    assert.equal(
+      resolvePostAuthDestination({ transaction: {}, app, routeRegistry }),
+      '/agentsam',
+    );
+  });
+
+  it('throws AUTH_APP_UNRESOLVED without app', () => {
+    assert.throws(
+      () => resolvePostAuthDestination({ transaction: {}, app: null, routeRegistry }),
+      (err) => err instanceof IdentityRoutingError && err.code === 'AUTH_APP_UNRESOLVED',
+    );
+  });
+
+  it('rejects cross-app return_to then uses authenticated entry', () => {
+    assert.equal(
+      resolvePostAuthDestination({
+        transaction: { return_to: '/admin/orders' },
+        app,
+        routeRegistry,
+      }),
+      '/agentsam',
+    );
+  });
+});
+
+describe('app verification', () => {
+  it('local-studio agentsam.app.json passes auth contract', () => {
+    const result = verifyAppPackage(LOCAL_STUDIO, { requireShellFiles: false });
+    assert.equal(result.ok, true, result.errors?.join('; '));
+  });
+
+  it('fails when authenticated entry missing', () => {
+    const result = verifyAppAuthContract({
+      schema: 'agentsam.app.v1',
+      id: 'broken',
+      name: 'Broken',
+      auth: { entry: { login: 'identity.login' } },
+      routes: { 'identity.login': { path: '/signin' } },
+    }, { requireShellFiles: false });
+    assert.equal(result.ok, false);
+    assert.ok(result.errors.some((e) => /authenticated|missing|AUTH_/i.test(e)));
+  });
+});
+
+describe('local-only SQLite identity (zero cloud)', () => {
+  it('migrates, provisions password user, OAuth transaction with app_id', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-id-'));
+    const dbFile = path.join(dir, 'identity.sqlite');
+    const db = await createLocalSqliteDatabase(dbFile);
+    await applySqliteIdentityMigrations(db);
+
+    const adapter = createSqliteIdentityAdapter(db);
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(LOCAL_STUDIO, 'agentsam.app.json'), 'utf8'),
+    );
+    const routeRegistry = createRouteRegistry([projectionFromAppManifest(manifest)]);
+    const identity = createIdentityService({
+      adapter,
+      app: { id: 'local-studio' },
+      routeRegistry,
+    });
+
+    const signup = await identity.signup({
+      email: 'local@example.test',
+      password: 'test-password-ok',
+      displayName: 'Local',
+    });
+    assert.equal(signup.ok, true);
+    assert.ok(signup.sessionId);
+
+    await adapter.createOAuthTransaction({
+      state: 'st_test',
+      provider: 'cloudflare',
+      codeVerifier: 'verifier',
+      returnTo: '/agentsam',
+      appId: 'local-studio',
+    });
+    const tx = await adapter.consumeOAuthTransaction('st_test');
+    assert.equal(tx.app_id, 'local-studio');
+    assert.equal(tx.return_to, '/agentsam');
+
+    await assert.rejects(
+      () => adapter.createOAuthTransaction({
+        state: 'st_bad',
+        provider: 'cloudflare',
+        codeVerifier: 'v',
+        returnTo: '/agentsam',
+      }),
+    );
+
+    assert.equal(SESSION_POLICY.agent.defaultTtlSeconds, 900);
+  });
+});

package/packages/identity/tests/session-routes-policy.test.mjs

@@ -0,0 +1,21 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { SESSION_POLICY, clampAgentSessionTtl } from '../src/core/session-policy.js';
+import { IDENTITY_ROUTE_IDS } from '../src/contracts/route-ids.js';
+
+describe('SESSION_POLICY', () => {
+  it('keeps browser and agent TTLs distinct', () => {
+    assert.equal(SESSION_POLICY.browser.ttlSeconds, 30 * 24 * 60 * 60);
+    assert.equal(SESSION_POLICY.agent.defaultTtlSeconds, 15 * 60);
+    assert.equal(clampAgentSessionTtl(30), 60);
+    assert.equal(clampAgentSessionTtl(900), 900);
+    assert.equal(clampAgentSessionTtl(999999), 24 * 60 * 60);
+  });
+});
+
+describe('IDENTITY_ROUTE_IDS', () => {
+  it('exposes semantic IDs only', () => {
+    assert.equal(IDENTITY_ROUTE_IDS.LOGIN, 'identity.login');
+    assert.ok(!String(IDENTITY_ROUTE_IDS.LOGIN).startsWith('/'));
+  });
+});

package/packages/providers/completeful/README.md

@@ -0,0 +1,38 @@
+# @inneranimalmedia/agentsam-provider-completeful
+
+Portable Completeful provider mechanics for AgentSam.
+
+This package is deliberately **not** a Fuel & Free Time data layer. It owns provider HTTP behavior, provider tool definitions/execution, structured provider errors, webhook signature verification, and normalized Completeful event envelopes.
+
+The host owns:
+
+- resolving `completeful.api_key` to a real secret such as Fuel & Free Time's `CAPP_KEY`;
+- account/shop configuration and authorization;
+- D1/R2 catalog mirrors and curation;
+- business workflows such as `fnf.order.sync`;
+- mapping provider events like `completeful.order.created` into domain events such as `commerce.order.created`;
+- execution receipts, queues, hook persistence, approvals and UI.
+
+## First slice
+
+The initial read-first tool surface is:
+
+- `completeful.shop.list`
+- `completeful.shop.get`
+- `completeful.catalog.list`
+- `completeful.catalog.get`
+- `completeful.catalog.semantic`
+- `completeful.order.get`
+- `completeful.webhook.list`
+
+The first mutation set is also present, with fail-closed live-write checks and explicit side-effect/idempotency metadata:
+
+- `completeful.design.create`
+- `completeful.product.create`
+- `completeful.product.publish`
+- `completeful.order.quote`
+- `completeful.order.create`
+- `completeful.order.cancel`
+- `completeful.webhook.ensure`
+
+Order reads/writes declare redacted receipt policy for address/email fields, and webhook tools declare/redact secret-bearing paths. The Completeful pinned OpenAPI contract remains under `apps/ecommerce-cms-agentsam/providers/completeful/reference/`.

package/packages/providers/completeful/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@inneranimalmedia/agentsam-provider-completeful",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Portable Completeful provider adapter and AgentSam tool definitions.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./tools": "./src/tools.js",
+    "./webhooks": "./src/webhooks.js",
+    "./events": "./src/events.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22 <25"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/packages/providers/completeful/src/client.js

@@ -0,0 +1,162 @@
+export const DEFAULT_COMPLETEFUL_API_ORIGIN = 'https://vxapi.completeful.com';
+
+function trimSlashes(value) {
+  return String(value || '').replace(/\/+$/, '');
+}
+
+export function completefulApiBase(apiUrl = DEFAULT_COMPLETEFUL_API_ORIGIN) {
+  const configured = trimSlashes(apiUrl || DEFAULT_COMPLETEFUL_API_ORIGIN);
+  return configured.endsWith('/v1') ? configured : `${configured}/v1`;
+}
+
+export function completefulKeyMode(apiKey) {
+  const key = String(apiKey || '');
+  if (key.startsWith('capp_test_')) return 'test';
+  if (key.startsWith('capp_live_')) return 'live';
+  return key ? 'unknown' : 'missing';
+}
+
+export class CompletefulApiError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'CompletefulApiError';
+    this.status = details.status || 502;
+    this.code = details.code || null;
+    this.requestId = details.requestId || null;
+    this.path = details.path || null;
+    this.remediation = details.remediation || null;
+    this.details = details.details || null;
+    this.providerBody = details.providerBody || null;
+  }
+
+  toJSON() {
+    return {
+      error: this.message,
+      code: this.code,
+      request_id: this.requestId,
+      path: this.path,
+      remediation: this.remediation,
+      details: this.details,
+    };
+  }
+}
+
+function buildUrl(base, path, query) {
+  const normalizedPath = String(path || '').startsWith('/') ? String(path) : `/${path}`;
+  const url = new URL(`${base}${normalizedPath}`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined || value === null || value === '') continue;
+      url.searchParams.set(key, String(value));
+    }
+  }
+  return url;
+}
+
+async function parseProviderResponse(response) {
+  const text = await response.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text.slice(0, 4000) };
+  }
+}
+
+export function createCompletefulClient({
+  apiKey,
+  apiUrl = DEFAULT_COMPLETEFUL_API_ORIGIN,
+  allowLiveWrites = false,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new TypeError('Completeful client requires a fetch implementation');
+  }
+
+  const base = completefulApiBase(apiUrl);
+  const mode = completefulKeyMode(apiKey);
+
+  function assertConfigured() {
+    if (mode !== 'missing') return;
+    throw new CompletefulApiError('Completeful API key is missing', {
+      status: 503,
+      code: 'completeful_not_configured',
+      remediation: 'Resolve a Completeful API key through the host authority adapter.',
+    });
+  }
+
+  function assertMutationAllowed() {
+    assertConfigured();
+    if (mode === 'test') return;
+    if (mode === 'live' && allowLiveWrites) return;
+    throw new CompletefulApiError('Completeful live writes are disabled', {
+      status: 409,
+      code: 'completeful_live_writes_disabled',
+      remediation: 'Use a capp_test_ key or explicitly enable live writes in the host configuration.',
+    });
+  }
+
+  async function request(method, path, { query = null, body = undefined, idempotencyKey = null, headers = null } = {}) {
+    assertConfigured();
+
+    const url = buildUrl(base, path, query);
+    const requestHeaders = new Headers(headers || {});
+    requestHeaders.set('Accept', 'application/json');
+    requestHeaders.set('Authorization', `Bearer ${apiKey}`);
+
+    let requestBody = body;
+    if (body !== undefined && body !== null && !(body instanceof FormData)) {
+      requestHeaders.set('Content-Type', 'application/json');
+      requestBody = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+    if (idempotencyKey) requestHeaders.set('Idempotency-Key', idempotencyKey);
+
+    const response = await fetchImpl(url.toString(), {
+      method,
+      headers: requestHeaders,
+      body: requestBody,
+    });
+
+    const data = await parseProviderResponse(response);
+    const requestId =
+      response.headers.get('x-request-id') ||
+      response.headers.get('x-capp-request-id') ||
+      data?.request_id ||
+      null;
+
+    const meta = {
+      status: response.status,
+      request_id: requestId,
+      mode: response.headers.get('x-capp-mode') || null,
+      dry_run: response.headers.get('x-capp-dry-run') === 'true',
+    };
+
+    if (!response.ok) {
+      const provider = data && typeof data === 'object' ? data : {};
+      throw new CompletefulApiError(
+        provider.error || provider.message || `Completeful request failed (${response.status})`,
+        {
+          status: response.status,
+          code: provider.code || 'completeful_request_failed',
+          requestId,
+          path: provider.path || url.pathname,
+          remediation: provider.remediation || null,
+          details: provider.details || null,
+          providerBody: provider,
+        },
+      );
+    }
+
+    return { data, meta };
+  }
+
+  return {
+    providerKey: 'completeful',
+    apiBase: base,
+    keyMode: mode,
+    allowLiveWrites: Boolean(allowLiveWrites),
+    request,
+    assertConfigured,
+    assertMutationAllowed,
+  };
+}

package/packages/providers/completeful/src/events.js

@@ -0,0 +1,49 @@
+function normalizeTopic(topic) {
+  return String(topic || 'unknown')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '.')
+    .replace(/^\.+|\.+$/g, '') || 'unknown';
+}
+
+function providerObjectId(event) {
+  const data = event?.data || {};
+  return data.order_id || data.product_id || data.shop_id || data.id || event?.resource_id || null;
+}
+
+function toUnixMilliseconds(value, fallback = Date.now()) {
+  if (value == null || value === '') return fallback;
+  if (Number.isFinite(Number(value))) {
+    const n = Number(value);
+    return n > 1e12 ? Math.floor(n) : Math.floor(n * 1000);
+  }
+  const parsed = Date.parse(String(value));
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+export function normalizeCompletefulEvent(event, context = {}) {
+  const topic = normalizeTopic(event?.type);
+  const id = String(event?.id || context.id || crypto.randomUUID());
+  const subject = providerObjectId(event);
+  return {
+    id,
+    eventKey: `completeful.${topic}`,
+    occurredAt: toUnixMilliseconds(event?.created ?? event?.created_at, context.occurredAt),
+    source: {
+      kind: 'webhook',
+      provider: 'completeful',
+      ref: context.webhookId || undefined,
+      metadata: {
+        provider_event_id: event?.id || null,
+        provider_webhook_id: context.providerWebhookId || null,
+        shop_id: context.shopId || event?.data?.shop_id || null,
+      },
+    },
+    payload: event,
+    accountId: context.accountId,
+    subject: subject ? String(subject) : undefined,
+    correlationId: context.correlationId,
+    causationId: context.causationId,
+    metadata: context.metadata,
+  };
+}

package/packages/providers/completeful/src/index.js

@@ -0,0 +1,22 @@
+export {
+  DEFAULT_COMPLETEFUL_API_ORIGIN,
+  CompletefulApiError,
+  completefulApiBase,
+  completefulKeyMode,
+  createCompletefulClient,
+} from './client.js';
+
+export {
+  COMPLETEFUL_TOOL_DEFINITIONS,
+  getCompletefulToolDefinition,
+  executeCompletefulProviderTool,
+  createCompletefulProviderAdapter,
+} from './tools.js';
+
+export {
+  COMPLETEFUL_WEBHOOK_TOLERANCE_SECONDS,
+  computeCompletefulWebhookSignature,
+  verifyCompletefulWebhook,
+} from './webhooks.js';
+
+export { normalizeCompletefulEvent } from './events.js';