@memory-nexus/bot-buyer-sdk

Starter TypeScript SDK for third-party bot builders to integrate:

1. bot-native purchase flow (catalog -> intent -> confirm -> entitlement)
2. memory filing and semantic recall (remember, recall, connect, context)

Install

npm install @memory-nexus/bot-buyer-sdk

Quick Start

import { BotBuyerClient } from "@memory-nexus/bot-buyer-sdk";

const client = new BotBuyerClient({
  baseUrl: "https://api.memory-nexus.org",
  apiKey: process.env.MEMORY_API_KEY,
});

const catalog = await client.getCatalog();
const product = catalog.products[0];

const create = await client.createPurchaseIntent(
  {
    product_id: "memory-api-hosted",
    tier: "solo",
    preferred_rail: "card",
    buyer_type: "bot",
    buyer_ref: "bot://agent-alpha",
    max_budget_cents: 2500,
    allow_fallback: true,
    fallback_rail: "http402",
  },
  { idempotencyKey: BotBuyerClient.createIdempotencyKey("intent") },
);

await client.confirmPurchaseIntent(
  create.intent.id,
  {
    rail: "card",
    challenge_response: "pm_xxx",
    buyer_ref: "bot://agent-alpha",
  },
  { idempotencyKey: BotBuyerClient.createIdempotencyKey("confirm") },
);

await client.remember({
  content: "Decision: adopt strict gateway contract checks.",
  context: "project:alpha:decisions",
  importance: 0.9,
  metadata: { project: "alpha", kind: "decision", owner: "planner-bot" },
});

Retry Middleware

The client applies retry middleware by default:

1. retries GET, POST, DELETE
2. retries status codes: 408, 409, 425, 429, 500, 502, 503, 504
3. exponential backoff with jitter

Override defaults:

const client = new BotBuyerClient({
  retryPolicy: {
    maxAttempts: 4,
    baseDelayMs: 300,
    maxDelayMs: 5000,
  },
});

Memory Filing Pattern

Recommended bot contexts:

1. project:<name>:decisions
2. project:<name>:research
3. project:<name>:tasks
4. ops:incidents

Recommended metadata keys:

1. project
2. kind
3. owner
4. source
5. timestamp