@aaes-ai/govern-sdk 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@aaes-ai/govern-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "TypeScript/JavaScript SDK for AAES — the AI governance platform for the action layer: permissions, human approvals, and spending limits on routed agent actions",
+  "license": "LicenseRef-AAES-Proprietary",
+  "keywords": ["aaes", "ai-governance", "agentic-ai", "agent-governance", "ai-agents", "agent-permissions", "human-approval", "spending-limits", "audit-trail"],
+  "type": "module",
+  "main": "./aaes.mjs",
+  "types": "./aaes.d.mts",
+  "exports": {
+    ".": {
+      "types": "./aaes.d.mts",
+      "import": "./aaes.mjs"
+    },
+    "./wire": {
+      "types": "./wire.d.ts"
+    }
+  },
+  "files": [
+    "aaes.mjs",
+    "aaes.d.mts",
+    "wire.d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aaes-ai/aaes.git",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://aaes.ai/developers/sdks.html",
+  "bugs": "https://github.com/aaes-ai/aaes/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test *.test.mjs"
+  }
+}

package/wire.d.ts

@@ -0,0 +1,78 @@
+// Wire response shapes from api/openapi.yaml. These retain daemon field names.
+export type ModelRequest = { "model": string; "stream"?: boolean; };
+export type ModelUsage = { "input_tokens": number; "output_tokens": number; "total_tokens": number; "settled_minor": number; "currency": string; "estimated"?: true; };
+export type ModelListOpenAI = { "object": "list"; "data": Array<{ "id": string; "object": "model"; "created": number; "owned_by": "aaes-govern"; }>; };
+export type ModelListAnthropic = { "data": Array<{ "type": "model"; "id": string; "display_name": string; "created_at": string; }>; "has_more": false; "first_id": string | null; "last_id": string | null; };
+export type ModelResponse = Record<string, unknown>;
+export type AnthropicError = { "type": "error"; "error": { "type": "authentication_error" | "permission_error" | "rate_limit_error" | "request_too_large" | "invalid_request_error" | "api_error"; "message": string; }; };
+export type OpenAIError = { "error": { "message": string; "type": "invalid_request_error" | "permission_error" | "insufficient_quota" | "api_error"; "param"?: string | null; "code": "invalid_api_key" | "govern_refused" | "govern_approval_required" | "insufficient_quota" | "request_too_large" | "invalid_request" | "upstream_error" | "govern_unavailable"; }; };
+export type ExecutionConstraints = { "business_id": string; "purpose": string; "configuration_hash": string; "policy_bundle_hash": string; "actor_ids": Array<string>; "steps": Array<ExecutionStep>; };
+export type ExecutionStep = { "step_id": string; "capability_hash": string; "capability_id": string; "version": string; "action": "read" | "write" | "create" | "update" | "delete" | "send" | "execute" | "pay" | "deploy" | "invoke" | "approve" | "share" | "transfer"; "resource_id": string; "endpoint": string; "method": string; "payload_hash": string; "amount": { "minor": number; "currency"?: string; }; "require_scoped_delegation"?: boolean; "require_human_approval"?: boolean; "prerequisites"?: Array<string>; };
+export type ExecutionContext = { "root_task_id": string; "constraints": ExecutionConstraints; "constraints_hash": string; "reservations": Record<string, unknown>; };
+export type Refusal = { "reason": string; "remedy"?: string; };
+export type IntegrationCredentialRef = { "path": string; "version"?: string; "key"?: string; };
+export type IntegrationCheckRequest = { "surface": string; "credential": IntegrationCredentialRef; };
+export type IntegrationCheckResponse = { "surface": string; "reached": boolean; "detail": string; "note": string; };
+export type IntegrationRotateRequest = { "surface": string; "secret_ref_id"?: string; "from": IntegrationCredentialRef; "to": IntegrationCredentialRef; };
+export type IntegrationRotateResponse = { "surface": string; "from": string; "to": string; "at": string; "authority": string; "note": string; "also_retired"?: string; };
+export type IntegrationRevokeRequest = { "surface": string; "reason"?: string; };
+export type IntegrationRevokeResponse = { "surface": string; "at": string; "authority": string; "reason": string; "note": string; };
+export type MeteringError = { "error": string; };
+export type LicenseStatus = { "state": string; "label": string; "reason": string; "warning": boolean; "persistent": boolean; "governance": string; "checked_at": string; "license": Record<string, unknown> | null; "usage": Record<string, unknown> | null; };
+export type UsageSummary = { "period": Record<string, unknown>; "index": "ok" | "unknown"; "governed_decisions": number; "records": Record<string, unknown>; "dedupe": "full" | "partial"; "retention_inside_period": boolean; "term": Record<string, unknown> | null; };
+export type IntegrationOpsError = { "error": string; };
+export type ActionRequest = { "tenant_id": string; "actor_id": string; "caller_task_id"?: string; "task_id"?: string; "effect_key_step"?: string; "capability": string; "tier": "R0" | "R1" | "R2" | "R3" | "R4" | number; "action"?: string; "correlation_id"?: string; "parent_intent_id"?: string; "contract_id"?: string; "model"?: string; "amount_minor": number; "amount_currency"?: string; "grant_ttl_ms"?: number; "provenance_status"?: "asserted" | "unknown"; "external_refs"?: Array<ExternalRef>; "payload"?: unknown; };
+export type ExternalRef = { "registry": string; "kind": string; "value": string; "source": "registered"; };
+export type Grant = { "grant_id": string; "actor_id": string; "tenant_id": string; "capability": string; "tier": string; "task_id"?: string; "issued_at": string; "expires_at": string; "ttl_seconds": number; "spend_cap_minor"?: number; "spend_cap_currency"?: string; "non_transferable": true; "budget_grant_id"?: string; "issuer"?: string; "signature"?: string; };
+export type GrantPresentRequest = { "grant_id": string; };
+export type GrantPresentView = { "grant_id": string; "actor_id": string; "tenant_id": string; "capability": string; "tier": string; "task_id"?: string; "issued_at": string; "expires_at": string; "spend_cap_minor"?: number; "spend_cap_currency"?: string; };
+export type GrantReceiptRequest = { "grant_id": string; "executed"?: boolean; "rail_confirmed"?: boolean; };
+export type GrantReceiptView = { "grant_id": string; "intent_id": string; "executed": boolean; "rail_confirmed": boolean; "receipt": Receipt; };
+export type Receipt = { "receipt_id"?: string; "intent_id"?: string; "tenant_id"?: string; "task_id"?: string; "approval_id"?: string; "custody"?: string; "grant_id"?: string; "effect_id"?: string; "effect"?: string; "record_hash"?: string; "issued_at"?: string; "class"?: number; "rail_confirmed"?: boolean; "confirmed_at"?: string; "reported_by"?: string; "reported_at"?: string; "observed_at"?: string; "reported_outcome"?: string; "note"?: string; "result_mode"?: "inline_bounded" | "rendezvous"; "payload_returned"?: boolean; "result_bytes"?: number; "result_content_type"?: string; "result_digest"?: string; "result_resource_id"?: string; "receipt_hash"?: string; "policy_bundle_hash"?: string; "input_hash"?: string; "engine_version"?: string; "model_usage"?: ModelUsage; };
+export type ActionResponse = { "allowed": boolean; "approval_id"?: string; "approval_state"?: "pending" | "raised"; "approval_expires_at"?: string; "deferred"?: boolean; "reason"?: string; "intent_id"?: string; "grant"?: Grant; "receipt"?: Receipt; "latency_added_ms": number; };
+export type BrokeredRequest = { "tenant_id": string; "actor_id": string; "caller_task_id"?: string; "task_id"?: string; "effect_key_step"?: string; "capability": string; "tier": "R0" | "R1" | "R2" | "R3" | "R4" | number; "action"?: string; "correlation_id"?: string; "parent_intent_id"?: string; "contract_id"?: string; "model"?: string; "provenance_status"?: "asserted" | "unknown"; "amount_minor": number; "amount_currency"?: string; "grant_ttl_ms"?: number; "external_refs"?: Array<ExternalRef>; "payload"?: unknown; };
+export type Outcome = { "executed": boolean; "status_code"?: number; "rail_effect_id"?: string; "rail_confirmed": boolean; "latency_added_ms": number; "response_digest"?: string; "result"?: { "mode": "inline_bounded"; "content_type": string; "bytes": number; "digest"?: string; "body_base64"?: string; }; "result_resource_id"?: string; };
+export type BrokeredResponse = { "allowed": boolean; "approval_id"?: string; "approval_state"?: "pending" | "raised"; "approval_expires_at"?: string; "deferred"?: boolean; "reason"?: string; "intent_id"?: string; "grant"?: Grant; "receipt"?: Receipt; "latency_added_ms": number; "outcome": Outcome; };
+export type FederateRequest = { "capability": string; "action"?: string; "task_id": string; "effect_key_step": string; "amount_minor": number; "amount_currency"?: string; "grant_ttl_ms"?: number; "rotate"?: boolean; "correlation_id"?: string; };
+export type FederateResponse = { "allowed": boolean; "reason"?: string; "intent_id"?: string; "grant"?: FederateGrant; };
+export type FederateGrant = { "federation_id": string; "intent_id": string; "decision_grant_id"?: string; "tenant_id": string; "actor_id": string; "capability": string; "capability_version"?: string; "actions": Array<string>; "resource_id"?: string; "task_id"?: string; "data_class"?: string; "tier": string; "spend_cap"?: { "minor"?: number; "currency"?: string; }; "scope_key": string; "backend": "custody" | "oauth_token_exchange" | "aws_sts_web_identity" | "azure_federated_credential" | "gcp_workload_identity" | "customer_broker"; "locator": FederateLocator; "issued_at": string; "expires_at": string; "ttl_seconds": number; "material": FederateMaterial; "record": FederateRecord; };
+export type FederateLocator = { "capability": string; "endpoint": string; "method"?: string; "authority"?: string; "resource_id"?: string; };
+export type FederateMaterial = { "kind": "credential" | "instructions"; "credential"?: string; "instructions"?: FederateInstructions; "expires_at"?: string; "audience"?: string; };
+export type FederateInstructions = { "backend": string; "method": string; "url": string; "headers"?: Record<string, unknown>; "form"?: Record<string, unknown>; "json"?: Record<string, unknown>; "subject_token_in": "form" | "json"; "subject_token_field": string; "subject_token_type"?: string; "duration_seconds"?: number; "documentation": string; "not_built"?: Array<string>; "notes"?: Array<string>; };
+export type FederateRecord = { "intent_id": string; "mode": "federated"; "payload_seen": false; "marker_receipt_hash"?: string; "receipt_id"?: string; };
+export type ObserveRequest = { "intent_id": string; "effect_id"?: string; "outcome"?: string; "observed_at"?: string; "note"?: string; };
+export type ObserveResponse = { "intent_id": string; "receipt": Receipt; "label": string; "enforcement": string; "counts_toward_coverage": false; };
+export type CapabilityEntry = { "registration_hash"?: string; "policy_bundle_hash"?: string; "capability_id": string; "version": string; "pinned": boolean; "kind"?: string; "owner": string; "risk_tier": string; "actions"?: Array<string>; "resource_id"?: string; "data_class"?: string; "custody"?: string; "enforcement": string; "result_mode"?: "digest" | "inline_bounded" | "rendezvous"; "result_resource_id"?: string; "result_ack_owner"?: string; "result_ack_reason"?: string; "task_id"?: string; "caller_task_id"?: string; };
+export type CapabilitiesResponse = { "tenant_id": string; "actor_id": string; "capabilities": Array<CapabilityEntry>; };
+export type CataloguePolicy = { "policy_id": string; "label": string; "required": number; "min_humans": number; "classes": Array<string>; "authority": string; };
+export type CatalogueEntry = { "capability_id": string; "version": string; "kind"?: string; "owner": string; "risk_tier": string; "actions": Array<string>; "resource_id"?: string; "data_class": string; "custody"?: string; "policy": CataloguePolicy; };
+export type CatalogueResponse = { "tenant_id": string; "actor_id": string; "requestable": Array<CatalogueEntry>; };
+export type AccessRequestCreate = { "capability": string; "actions": Array<string>; "resource_id"?: string; "data_class"?: string; "tier": string; "budget_minor"?: number; "budget_currency"?: string; "ttl_seconds": number; "task_id": string; "justification": string; "surface_resource_id"?: string; "team_id"?: string; "duration"?: "just_in_time" | "standing" | "scheduled_window" | "task_bound" | "break_glass"; "review_days"?: number; "window_start"?: string; "window_end"?: string; "window_timezone"?: string; };
+export type Quorum = { "required": number; "humans": number; "policy": string; };
+export type AccessRequestCreated = { "request_id": string; "state": string; "needed": Quorum; "duration"?: ""; "reviewed"?: boolean; };
+export type AccessApprovalState = { "approval_id": string; "state": "pending" | "granted" | "rejected" | "expired"; "decided_by"?: string; "decided_at"?: string; };
+export type AccessRequest = { "request_id": string; "state": "pending" | "granted" | "denied" | "returned" | "expired" | "revoked"; "needed": Quorum; "tenant_id"?: string; "actor_id"?: string; "capability"?: string; "actions"?: Array<string>; "resource_id"?: string; "data_class"?: string; "tier"?: string; "budget_minor"?: number; "budget_currency"?: string; "ttl_seconds"?: number; "task_id"?: string; "justification"?: string; "surface_resource_id"?: string; "team_id"?: string; "duration"?: "just_in_time" | "standing" | "scheduled_window" | "task_bound" | "break_glass"; "review_ttl_seconds"?: number; "window_start"?: string; "window_end"?: string; "window_timezone"?: string; "review_required"?: boolean; "reviewed_by"?: string; "reviewed_at"?: string; "reviewed"?: boolean; "approval_id"?: string; "approvals"?: Array<AccessApprovalState>; "decided_by"?: Array<string>; "decided_at"?: string; "expires_at"?: string; "created_at"?: string; "reason"?: string; };
+export type RevokeRequest = { "reason"?: string; };
+export type ManagerCard = { "CardID"?: string; "ApprovalID"?: string; "IntentID"?: string; "TaskID"?: string; "Approver"?: string; "PayloadHash"?: string; "PolicyID"?: string; "Action"?: string; "Summary"?: string; "Quorum"?: string; "RaisedAt"?: string; "ExpiresAt"?: string; "Via"?: string; "ForApprover"?: string; };
+export type ManagerCardsResponse = { "tenant_id": string; "actor_id": string; "cards": Array<ManagerCard>; "note"?: string; };
+export type ManagerCardDecision = { "card_id": string; "approval_id": string; "payload_hash": string; "policy_id"?: string; "grant": boolean; "reason"?: string; };
+export type ManagerCardDecisionRecorded = { "tenant_id": string; "actor_id": string; "card_id": string; "approval_id": string; "recorded": boolean; };
+export type HealthResponse = { "status": "ok"; };
+export type ReadinessResponse = { "status": "ready" | "not ready"; "reason"?: string; "bundle_id"?: string; "engine_version"?: string; "full_flush"?: boolean; "callers_verified"?: boolean; "unauthenticated"?: boolean; "task_bound"?: boolean; "taskless_allowed"?: boolean; "approvals_wired"?: boolean; "custody_on_record"?: boolean; "capabilities_registered"?: number; "capabilities_note"?: string; };
+export type CallbackResult = { "recorded": boolean; "code"?: string; "refusal"?: string; "approval_id"?: string; "approver"?: string; "granted"?: boolean; "quorum"?: string; "quorum_satisfied"?: boolean; };
+export type PageInfo = { "limit": number; "returned": number; "has_more": boolean; "next_cursor"?: string; };
+export type Task = { "task_id": string; "tenant_id": string; "parent_id"?: string; "title": string; "state": "draft" | "open" | "claimed" | "blocked" | "completed" | "abandoned" | "expired"; "sponsor"?: string; "assignee"?: string; "budget_minor": number; "committed_minor": number; "remaining_minor": number; "currency"?: string; "human_free_approval"?: boolean; "human_free_approval_sponsor"?: string; "human_free_approval_at"?: string; "deadline"?: string; "depth"?: number; "required_approvals"?: Array<string>; "created_at": string; "updated_at": string; "revision": number; };
+export type TaskPage = { "items": Array<Task>; "page": PageInfo; };
+export type ExternalApproval = { "approval_id": string; "task_id": string; "intent_id": string; "requester": string; "action"?: string; "state": "pending" | "granted" | "rejected" | "expired"; "approver"?: string; "deciders"?: Array<string>; "created_at": string; "expires_at": string; "capability"?: string; "amount_minor"?: number; "amount_currency"?: string; "operate"?: { "company_id": string; "agent_id": string; "run_id"?: string; "issue_id"?: string; "project_id"?: string; }; };
+export type ExternalApprovalList = { "items": Array<ExternalApproval>; };
+export type OperateSettlement = { "company_id": string; "agent_id": string; "run_id": string; "complete": boolean; "settled": boolean; };
+export type ExternalSpend = { "company_id": string; "rows": Array<ExternalSpendRow>; };
+export type ExternalSpendRow = { "operate_agent_id": string; "actor_id": string; "project_id"?: string; "currency": string; "permits": number; "refusals": number; "reserved_minor": number; "settled_minor": number; "model_calls": number; };
+export type ExternalApprovalDecision = { "decision": "grant" | "reject"; "reason"?: string; };
+export type ExternalApprovalDecided = { "approval": ExternalApproval; "outcome": "grant" | "reject" | "recommended"; "operate_notified": boolean; };
+export type Approval = { "approval_id": string; "tenant_id": string; "task_id"?: string; "intent_id"?: string; "state": "not_required" | "pending" | "granted" | "rejected" | "expired"; "approver"?: string; "approver_kind"?: string; "approver_authority"?: string; "approver_sponsor"?: string; "requester"?: string; "sponsor"?: string; "action"?: string; "reason"?: string; "payload_hash"?: string; "bundle_hash"?: string; "engine_version"?: string; "approval_policy_id"?: string; "created_at": string; "expires_at": string; "decided_at"?: string; };
+export type ApprovalPage = { "items": Array<Approval>; "page": PageInfo; };
+export type Entitlement = { "request_id": string; "tenant_id": string; "actor_id": string; "capability": string; "actions"?: Array<string>; "resource_id"?: string; "data_class"?: string; "tier": string; "budget"?: { "minor"?: number; "currency"?: string; }; "state": "usable" | "expired" | "revoked"; "expires_at": string; "granted_by"?: string; "revoked_at"?: string; "revoked_by"?: string; };
+export type EntitlementPage = { "items": Array<Entitlement>; "page": PageInfo; };
+export type ReceiptView = { "execution_state"?: "claimed" | "not_dispatched"; "receipt_id": string; "intent_id": string; "tenant_id": string; "task_id"?: string; "approval_id"?: string; "custody"?: string; "grant_id"?: string; "effect_id"?: string; "effect"?: string; "class": "denied" | "minted_unused" | "authorized" | "executed" | "deferred"; "record_hash": string; "issued_at": string; "rail_confirmed": boolean; "confirmed_at"?: string; "reported_by"?: string; "reported_at"?: string; "observed_at"?: string; "reported_outcome"?: string; "note"?: string; "receipt_hash"?: string; "policy_bundle_hash": string; "input_hash": string; "engine_version": string; "counts_toward_coverage": boolean; "result_mode"?: "digest" | "inline_bounded" | "rendezvous"; "payload_returned"?: true; "result_resource_id"?: string; "model_usage"?: ModelUsage; };
+export type ReceiptPage = { "items": Array<ReceiptView>; "page": PageInfo; };