@pliuz/sdk 0.1.0

package/examples/basic.ts

@@ -0,0 +1,70 @@
+/**
+ * Bare PliuzClient — create approval, poll, report execution by hand.
+ *
+ * Use this when you need full control over the flow. For 99% of cases,
+ * use gated() — see gated-basic.ts.
+ *
+ * Run:
+ *   export PLIUZ_API_KEY=pli_live_...
+ *   npx tsx examples/basic.ts
+ */
+
+import { PliuzClient, PliuzPolicyError } from '@pliuz/sdk'
+
+async function main(): Promise<void> {
+  const pliuz = new PliuzClient()
+
+  // 1. Submit the approval request.
+  let created
+  try {
+    created = await pliuz.createApproval({
+      tool_name: 'example_tool',
+      tool_args: { foo: 'bar', value: 42 },
+      context_messages: ['Triggered from examples/basic.ts'],
+      idempotency_key: 'basic-example-ts-001', // safe to retry
+    })
+  } catch (e) {
+    if (e instanceof PliuzPolicyError) {
+      console.log(`No policy matched: ${e.message}`)
+      console.log("Create a policy targeting tool_name='example_tool' in the dashboard.")
+      return
+    }
+    throw e
+  }
+
+  console.log(`Created approval ${created.id} (status=${created.status})`)
+
+  // 2. Poll if pending. gated() does this for you.
+  if (created.status === 'pending') {
+    for (let attempt = 0; attempt < 60; attempt++) {
+      await new Promise((resolve) => setTimeout(resolve, 2000))
+      const approval = await pliuz.getApproval(created.id)
+      console.log(`  poll #${attempt}: status=${approval.status}`)
+      if (approval.status !== 'pending') break
+    }
+  }
+
+  // 3. Read final state.
+  const final = await pliuz.getApproval(created.id)
+  if (final.status !== 'approved') {
+    console.log(`Not approved: ${final.status} (${final.decision_reason})`)
+    return
+  }
+
+  // 4. Do the work.
+  console.log('Approved — running the gated action.')
+  const result = { didSomething: true }
+
+  // 5. Report execution.
+  const report = await pliuz.reportExecution(final.id, {
+    status: 'success',
+    latency_ms: 42,
+    target_response_excerpt: JSON.stringify(result),
+  })
+  console.log(`Reported execution: seq=${report.event_seq}`)
+}
+
+main().catch((e) => {
+  console.error('Error:', e)
+  process.exit(1)
+})

package/examples/gated-basic.ts

@@ -0,0 +1,62 @@
+/**
+ * gated() — the headline API. Wrap a function, call it normally.
+ *
+ * The wrapper handles create + poll + execute + report internally.
+ *
+ * Run:
+ *   export PLIUZ_API_KEY=pli_live_...
+ *   npx tsx examples/gated-basic.ts
+ */
+
+import { gated, PliuzRejectedError } from '@pliuz/sdk'
+
+interface Customer {
+  id: string
+  ssn: string
+  dob: string
+  email: string
+}
+
+const issueRefund = gated(
+  {
+    policy: 'refund',
+    redact: ['customer.ssn', 'customer.dob'], // never leave plaintext
+    timeoutMs: 120_000, // give the human 2 minutes
+    // toolArgs maps positional args into a named dict for Pliuz audit log
+    toolArgs: (customerId: string, amountCents: number, customer: Customer) => ({
+      customer_id: customerId,
+      amount_cents: amountCents,
+      customer,
+    }),
+  },
+  async (customerId: string, amountCents: number, _customer: Customer) => {
+    console.log(`  → executing refund for ${customerId} ($${(amountCents / 100).toFixed(2)})`)
+    // In a real app: await stripe.refunds.create({ customer: customerId, amount: amountCents })
+    return { refund_id: 're_fake', amount: amountCents }
+  },
+)
+
+async function main(): Promise<void> {
+  const customer: Customer = {
+    id: 'cus_123',
+    ssn: '123-45-6789', // ← redacted before send
+    dob: '1990-01-01', // ← redacted before send
+    email: 'customer@example.com', // ← visible to approver
+  }
+
+  try {
+    const result = await issueRefund('cus_123', 5000, customer)
+    console.log(`Done: ${JSON.stringify(result)}`)
+  } catch (e) {
+    if (e instanceof PliuzRejectedError) {
+      console.log(`Rejected by approver: ${e.reason}`)
+      return
+    }
+    throw e
+  }
+}
+
+main().catch((e) => {
+  console.error('Error:', e)
+  process.exit(1)
+})

package/examples/vercel-ai-agent.ts

@@ -0,0 +1,65 @@
+/**
+ * Vercel AI SDK agent with a gated tool — drop-in for any AI SDK agent.
+ *
+ * gatedTool() wraps tool({...}) from `ai`. The LLM sees the tool
+ * identically (same description, parameters); only execute() is gated.
+ *
+ * Install:
+ *   npm install @pliuz/sdk ai @ai-sdk/openai zod
+ *
+ * Run:
+ *   export PLIUZ_API_KEY=pli_live_...
+ *   export OPENAI_API_KEY=sk-...
+ *   npx tsx examples/vercel-ai-agent.ts
+ */
+
+import { tool, generateText } from 'ai'
+import { openai } from '@ai-sdk/openai'
+import { z } from 'zod'
+import { gatedTool } from '@pliuz/sdk/adapters/ai'
+
+const issueRefund = gatedTool(
+  {
+    policy: 'refund',
+    redact: ['customer_id'], // strip from audit log
+  },
+  tool({
+    description: 'Issue a refund to a customer. Requires human approval.',
+    parameters: z.object({
+      customer_id: z.string().describe('The Stripe customer ID'),
+      amount_cents: z.number().int().positive().describe('Amount to refund in cents'),
+    }),
+    execute: async ({ customer_id, amount_cents }) => {
+      // In a real app: stripe.refunds.create({ customer: customer_id, amount: amount_cents })
+      return { refund_id: 're_fake', customer: customer_id, amount: amount_cents }
+    },
+  }),
+)
+
+const getCustomerEmail = tool({
+  description: "Look up a customer's email by ID. Safe to run without approval.",
+  parameters: z.object({
+    customer_id: z.string(),
+  }),
+  execute: async ({ customer_id }) => {
+    void customer_id
+    return { email: 'customer@example.com' }
+  },
+})
+
+async function main(): Promise<void> {
+  const { text, toolCalls } = await generateText({
+    model: openai('gpt-4o'),
+    tools: { issueRefund, getCustomerEmail },
+    prompt: 'Refund customer cus_123 for $50. Look up their email first.',
+    maxSteps: 5,
+  })
+
+  console.log('Final response:', text)
+  console.log('Tool calls:', JSON.stringify(toolCalls, null, 2))
+}
+
+main().catch((e) => {
+  console.error('Error:', e)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@pliuz/sdk",
+  "version": "0.1.0",
+  "description": "Human-in-the-loop approval gates for AI agents — pause function calls for human review, then resume or abort.",
+  "keywords": [
+    "ai",
+    "agents",
+    "approval",
+    "audit",
+    "human-in-the-loop",
+    "llm",
+    "guardrails",
+    "vercel-ai-sdk"
+  ],
+  "homepage": "https://pliuz.dev",
+  "bugs": "https://github.com/mwhitex/pliuz/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mwhitex/pliuz.git",
+    "directory": "sdk-typescript"
+  },
+  "license": "Apache-2.0",
+  "author": "Pliuz",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./adapters/ai": {
+      "types": "./dist/adapters/ai.d.ts",
+      "import": "./dist/adapters/ai.js",
+      "require": "./dist/adapters/ai.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo 'ESLint config pending — tracked as post-0.1.0 improvement' && exit 0",
+    "format": "prettier --write src test",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run typecheck && npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "ai": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "ai": "^4.0.0",
+    "eslint": "^9.0.0",
+    "msw": "^2.6.0",
+    "prettier": "^3.3.0",
+    "react": "^19.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "yaml": "^2.9.0",
+    "zod": "^3.23.0"
+  }
+}