@auctra/sdk 0.7.20 → 0.7.21

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.7.21
+
+**Docs — first-call samples match the live gates**
+
+- Finance samples send the same amount on `payload.amount` and `metadata.amount`.
+- The `execute_sql` sample sets the action target to the authorized scope and uses a grant with no dollar cap.
+
 ## 0.7.20
 
 **Interop — OpenAPI method constraints on catalog mapping**

package/README.md

@@ -53,8 +53,10 @@ There is **no** public `createDelegation()` or `evaluateAction()`.
 
 ## Quick start
 
+Create the key in the console. Use an admin key for `authority.issue` and `createIntent`, and a write key for `action.execute`. Register the agent in Agents first, with a human sponsor. The model name is inventory. Auctra does not call it. HTTP 402 `plan_agent_limit` means the plan is full (Startup allows 25 agents): reuse one. Keep one live grant on that agent. The sample below is one finance action. The same client calls cover data access, messages, infrastructure, workflow, and tools. When a call fails, read `decision.reason` and `AuctraApiError.status` / `code`. The fix list is [Roadblocks](https://www.auctra.tech/docs#start-roadblocks): 402 `plan_agent_limit`, `plan_intent_limit`, 403 without an admin key, no grant for the action type, missing anchor token, `PROVENANCE_REQUIRED`, a hard limit (blocked, not queued), `SQL_SCOPE_EXCEEDED`, `require_approval`, `WORKLOAD_BIND_REQUIRED`, `ENVIRONMENT_MISMATCH`, and HTTP 409 on a second lease consume. `currently_authorized: false` on evidence verify is expected.
+
 ```typescript
-import { Auctra } from "@auctra/sdk";
+import { Auctra, withExecutionLease } from "@auctra/sdk";
 
 const auctra = new Auctra({
   apiKey: process.env.AUCTRA_API_KEY!,
@@ -69,51 +71,65 @@ const expiresAt = new Date(Date.now() + 30 * 864e5).toISOString();
 const { authority } = await auctra.authority.issue({
   subject: agentId,
   capabilities: ["send_payment"],
-  constraints: { maxAmount: 1200, currency: "USD" },
+  constraints: { maxAmount: 20, currency: "USD" },
   expiresAt,
 });
 
-// Declare human intent first — every action.execute needs the returned anchor_token
+// Declare human intent first. Save anchor_token. It is not returned on GET.
+const title = "Pay the docs vendor under $20";
 const { intent } = await auctra.createIntent({
-  title: "Pay matched vendor invoices",
+  title,
+  description: title,
   intentType: "payment",
   riskLevel: "high",
   maxRiskLevel: "critical",
   allowedActionTypes: ["send_payment"],
+  maxAmount: 20,
+  currency: "USD",
+  vendorAllowlist: ["vendor:docs-walkthrough"],
   expiresAt,
 });
 
-// Dry-run
-await auctra.action.evaluate({
-  agentId,
-  actionType: "send_payment",
-  payload: { amount: 500, currency: "USD" },
-  intent, // wires claimed_intent_id + intent_anchor_token
-});
-
-// Production enforcement path
 const decision = await auctra.action.execute(
   {
     agentId,
     actionType: "send_payment",
-    payload: { amount: 500, currency: "USD", target: "vendor:acme" },
-    intent, // do not pass claimedIntentId alone — omit anchor → require_approval
+    payload: { amount: 9, currency: "USD", target: "vendor:docs-walkthrough" },
+    intent, // id + anchor_token. The id alone returned blocked on a payment.
     action: {
-      target: "vendor:acme",
-      description: "Net-30 invoice payment",
+      target: "vendor:docs-walkthrough",
+      description: title,
       riskLevel: "medium",
+      metadata: {
+        inputs: [{
+          source: "billing",
+          source_type: "invoice",
+          trust_level: "internal",
+          authority: "none",
+          received_at: new Date().toISOString(),
+        }],
+        context_refs: [{
+          source_id: "invoice:docs",
+          fetched_at: new Date().toISOString(),
+          trust_level: "internal",
+        }],
+        amount: 9,
+        currency: "USD",
+      },
     },
   },
   { idempotencyKey: crypto.randomUUID() },
 );
 
 if (decision.decision === "allowed") {
-  // proceed
+  await withExecutionLease(auctra, decision, async () => {
+    // call your payment API here; Auctra does not hold that secret
+  }, { expectedActionType: "send_payment" });
 } else if (decision.decision === "require_approval") {
-  // Pass the decision object — SDK forwards approval_nonce automatically (TEST-004).
+  // Org policy or velocity hold. Open Authority Reviews. Not a missing-field payment.
   await auctra.approveActionRequest(decision, sponsorUserId, "Approved after review");
 } else {
-  // "blocked" includes over-maxAmount, unknown agent, revoked/expired grant
+  // blocked: missing provenance, missing anchor, over maxAmount, unknown agent, revoked grant
   throw new Error(decision.reason);
 }
 
@@ -121,6 +137,69 @@ const pack = await auctra.getActionRequest(decision.action_request_id);
 
 ```
 
+### Same calls for other action types
+
+Finance is not the only type. A message and a SQL query use the same intent object, the same lease consume, and a grant that lists that type. A dollar cap is only for types that carry an amount.
+
+```typescript
+await auctra.authority.issue({
+  subject: agentId,
+  capabilities: ["send_email", "execute_sql"],
+  expiresAt,
+});
+
+const mailIntent = (await auctra.createIntent({
+  title: "Notify the customer about the ticket",
+  description: "Notify the customer about the ticket",
+  allowedActionTypes: ["send_email"],
+  expiresAt,
+})).intent;
+
+const mail = await auctra.action.execute({
+  agentId,
+  actionType: "send_email",
+  intent: mailIntent,
+  payload: { target: "customer:docs" },
+  action: {
+    target: "customer:docs",
+    description: "Notify the customer about the ticket",
+    metadata: {
+      inputs: [{ source: "ticket", source_type: "case", trust_level: "internal", authority: "none", received_at: new Date().toISOString() }],
+    },
+  },
+});
+if (mail.decision === "allowed") {
+  await withExecutionLease(auctra, mail, async () => {
+    // call your mailer here
+  }, { expectedActionType: "send_email" });
+}
+
+const sqlIntent = (await auctra.createIntent({
+  title: "Read aggregate customer metrics",
+  description: "Read aggregate customer metrics",
+  allowedActionTypes: ["execute_sql"],
+  expiresAt,
+})).intent;
+
+const query = await auctra.action.execute({
+  agentId,
+  actionType: "execute_sql",
+  intent: sqlIntent,
+  payload: { target: "customers.aggregate_metrics" },
+  action: {
+    target: "customers.aggregate_metrics",
+    description: "Read aggregate customer metrics",
+    metadata: {
+      inputs: [{ source: "warehouse", source_type: "schema", trust_level: "internal", authority: "none", received_at: new Date().toISOString() }],
+      context_refs: [{ source_id: "schema:customers", fetched_at: new Date().toISOString(), trust_level: "internal" }],
+      sql: { requested_scope: "customers.aggregate_metrics", authorized_scope: "customers.aggregate_metrics" },
+    },
+  },
+});
+// requested_scope or the action target outside authorized_scope returns blocked SQL_SCOPE_EXCEEDED.
+// Omitting the target uses the action type name, and that name is also a requested scope.
+```
+
 ### Delegate (Child ⊆ Parent)
 
 ```typescript
@@ -149,7 +228,7 @@ const { intent } = await auctra.createIntent({ /* ... */ });
 await auctra.action.execute({ agentId, actionType, payload, intent, action: { /* ... */ } });
 ```
 
-**Do not** send `claimedIntentId` without `intentAnchorToken` — the runtime returns `require_approval` with a message about the missing anchor. That is intentional (fail-safe), not a policy misconfiguration.
+**Do not** send `claimedIntentId` without `intentAnchorToken`. On a payment that already included provenance, the id without the anchor token returned **blocked**, and the reason told the caller to send `intent_anchor_token`. A payment without `action.metadata.inputs` and `context_refs` returned **blocked** with `PROVENANCE_REQUIRED` and `CONTEXT_REFS_MISSING` before the intent check. `require_approval` is an org policy or a velocity hold, not the missing-token payment.
 
 Full onboarding guide: [`docs/integrations/intent-anchors.md`](../../docs/integrations/intent-anchors.md).
 

package/dist/cjs/types.js

@@ -2,6 +2,6 @@
 /** @auctra/sdk — Authority Protocol client (Stage 1.0 modular layout). */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_BASE_URL = exports.AUCTRA_SDK_VERSION = void 0;
-exports.AUCTRA_SDK_VERSION = "0.7.20";
+exports.AUCTRA_SDK_VERSION = "0.7.21";
 /** Production API + console host (Architecture A: colocated on app.auctra.tech). */
 exports.DEFAULT_BASE_URL = "https://app.auctra.tech";

package/dist/esm/types.d.ts

@@ -1,5 +1,5 @@
 /** @auctra/sdk — Authority Protocol client (Stage 1.0 modular layout). */
-export declare const AUCTRA_SDK_VERSION = "0.7.20";
+export declare const AUCTRA_SDK_VERSION = "0.7.21";
 /** Production API + console host (Architecture A: colocated on app.auctra.tech). */
 export declare const DEFAULT_BASE_URL = "https://app.auctra.tech";
 export type AgentEnvironment = "dev" | "staging" | "production";

package/dist/esm/types.js

@@ -1,4 +1,4 @@
 /** @auctra/sdk — Authority Protocol client (Stage 1.0 modular layout). */
-export const AUCTRA_SDK_VERSION = "0.7.20";
+export const AUCTRA_SDK_VERSION = "0.7.21";
 /** Production API + console host (Architecture A: colocated on app.auctra.tech). */
 export const DEFAULT_BASE_URL = "https://app.auctra.tech";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auctra/sdk",
-  "version": "0.7.20",
+  "version": "0.7.21",
   "description": "Authority Protocol SDK — issue portable authority, evaluate/execute actions, verify evidence",
   "homepage": "https://www.auctra.tech/docs",
   "bugs": {

package/src/types.ts

@@ -1,6 +1,6 @@
 /** @auctra/sdk — Authority Protocol client (Stage 1.0 modular layout). */
 
-export const AUCTRA_SDK_VERSION = "0.7.20";
+export const AUCTRA_SDK_VERSION = "0.7.21";
 
 /** Production API + console host (Architecture A: colocated on app.auctra.tech). */
 export const DEFAULT_BASE_URL = "https://app.auctra.tech";