@continuonai/rcan-ts 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+/**
+ * RCAN Robot URI — addressing scheme for RCAN v1.2.
+ *
+ * Format: rcan://<registry>/<manufacturer>/<model>/<version>/<device-id>
+ * Example: rcan://registry.rcan.dev/acme/robotarm/v2/unit-001
+ */
+declare class RobotURIError extends Error {
+    constructor(message: string);
+}
+interface RobotURIOptions {
+    manufacturer: string;
+    model: string;
+    version: string;
+    deviceId: string;
+    registry?: string;
+}
+declare class RobotURI {
+    readonly registry: string;
+    readonly manufacturer: string;
+    readonly model: string;
+    readonly version: string;
+    readonly deviceId: string;
+    private constructor();
+    /** Parse a RCAN URI string. Throws RobotURIError on invalid input. */
+    static parse(uri: string): RobotURI;
+    /** Build a RCAN URI from components. */
+    static build(opts: RobotURIOptions): RobotURI;
+    /** Full URI string: rcan://registry/manufacturer/model/version/device-id */
+    toString(): string;
+    /** Short namespace: manufacturer/model */
+    get namespace(): string;
+    /** HTTPS registry URL for this robot */
+    get registryUrl(): string;
+    /** Check if two URIs refer to the same robot */
+    equals(other: RobotURI): boolean;
+    toJSON(): object;
+}
+
+/**
+ * RCAN Message — command envelope for RCAN v1.2.
+ *
+ * A RCANMessage wraps a robot command with:
+ * - RCAN protocol version
+ * - Target Robot URI
+ * - Command name and parameters
+ * - Optional AI confidence score (§16)
+ * - Optional model identity (§16)
+ * - Optional Ed25519 signature
+ */
+
+interface SignatureBlock {
+    alg: string;
+    kid: string;
+    sig: string;
+}
+interface RCANMessageData {
+    rcan?: string;
+    cmd: string;
+    target: string | RobotURI;
+    params?: Record<string, unknown>;
+    confidence?: number;
+    modelIdentity?: string;
+    model_identity?: string;
+    signature?: SignatureBlock;
+    timestamp?: string;
+    [key: string]: unknown;
+}
+declare class RCANMessageError extends Error {
+    constructor(message: string);
+}
+declare class RCANMessage {
+    readonly rcan: string;
+    readonly cmd: string;
+    readonly target: string;
+    readonly params: Record<string, unknown>;
+    readonly confidence: number | undefined;
+    readonly modelIdentity: string | undefined;
+    readonly signature: SignatureBlock | undefined;
+    readonly timestamp: string;
+    constructor(data: RCANMessageData);
+    /** Whether this message has a signature block */
+    get isSigned(): boolean;
+    /** Whether this message was generated by an AI model (has confidence score) */
+    get isAiDriven(): boolean;
+    /** Serialize to a plain object */
+    toJSON(): Record<string, unknown>;
+    /** Serialize to JSON string */
+    toJSONString(indent?: number): string;
+    /** Parse from a plain object or JSON string */
+    static fromJSON(data: string | Record<string, unknown>): RCANMessage;
+}
+
+/**
+ * RCAN Safety Gates — confidence and human-in-the-loop gating (§16).
+ */
+declare class GateError extends Error {
+    constructor(message: string);
+}
+declare class ConfidenceGate {
+    readonly threshold: number;
+    constructor(threshold?: number);
+    /** Returns true if the confidence score meets the threshold. */
+    allows(confidence: number): boolean;
+    /** Returns the margin (positive = allowed, negative = blocked). */
+    margin(confidence: number): number;
+    /** Throw if confidence is below threshold. */
+    assert(confidence: number, action?: string): void;
+}
+type ApprovalStatus = "approved" | "denied" | "pending";
+interface PendingApproval {
+    token: string;
+    action: string;
+    context: Record<string, unknown>;
+    createdAt: string;
+    status: ApprovalStatus;
+    reason?: string;
+}
+declare class HiTLGate {
+    private _pending;
+    /**
+     * Request human approval for an action.
+     * Returns an approval token to poll or pass to approve/deny.
+     */
+    request(action: string, context?: Record<string, unknown>): string;
+    /** Approve a pending request. */
+    approve(token: string): void;
+    /** Deny a pending request with an optional reason. */
+    deny(token: string, reason?: string): void;
+    /** Check the status of a pending approval. */
+    check(token: string): ApprovalStatus;
+    /** Get all pending approvals. */
+    get pendingApprovals(): PendingApproval[];
+    /** Get the full approval record. */
+    getApproval(token: string): PendingApproval | undefined;
+    /** Clear resolved (approved/denied) approvals. */
+    clearResolved(): void;
+}
+
+/**
+ * RCAN Audit Chain — tamper-evident commitment records (§16).
+ *
+ * Each CommitmentRecord is sealed with an HMAC-SHA256 over its content.
+ * Records are chained via previousHash, creating a forensic audit trail.
+ */
+interface CommitmentRecordData {
+    action: string;
+    robotUri?: string;
+    confidence?: number;
+    modelIdentity?: string;
+    params?: Record<string, unknown>;
+    safetyApproved?: boolean;
+}
+interface CommitmentRecordJSON {
+    recordId: string;
+    action: string;
+    robotUri: string;
+    confidence?: number;
+    modelIdentity?: string;
+    params: Record<string, unknown>;
+    safetyApproved: boolean;
+    timestamp: string;
+    contentHash: string;
+    previousHash: string | null;
+    hmac: string;
+}
+declare class AuditError extends Error {
+    constructor(message: string);
+}
+declare class CommitmentRecord {
+    readonly recordId: string;
+    readonly action: string;
+    readonly robotUri: string;
+    readonly confidence: number | undefined;
+    readonly modelIdentity: string | undefined;
+    readonly params: Record<string, unknown>;
+    readonly safetyApproved: boolean;
+    readonly timestamp: string;
+    readonly contentHash: string;
+    readonly previousHash: string | null;
+    readonly hmac: string;
+    private constructor();
+    static create(data: CommitmentRecordData, secret: string, previousHash?: string | null): CommitmentRecord;
+    verify(secret: string): boolean;
+    toJSON(): CommitmentRecordJSON;
+    static fromJSON(obj: CommitmentRecordJSON): CommitmentRecord;
+}
+interface ChainVerifyResult {
+    valid: boolean;
+    count: number;
+    errors: string[];
+}
+declare class AuditChain {
+    private _records;
+    private _secret;
+    constructor(secret: string);
+    get records(): readonly CommitmentRecord[];
+    append(data: CommitmentRecordData): CommitmentRecord;
+    verifyAll(): ChainVerifyResult;
+    toJSONL(): string;
+    static fromJSONL(text: string, secret: string): AuditChain;
+}
+
+/**
+ * RCAN Validation — validate messages, configs, and URIs.
+ *
+ * Each function returns a ValidationResult with ok, issues, warnings, info.
+ */
+interface ValidationResult {
+    ok: boolean;
+    issues: string[];
+    warnings: string[];
+    info: string[];
+}
+declare function validateURI(uri: string): ValidationResult;
+declare function validateMessage(data: unknown): ValidationResult;
+interface RCANConfig {
+    rcan_version?: string;
+    metadata?: {
+        manufacturer?: string;
+        model?: string;
+        version?: string;
+        rrn?: string;
+        rcan_uri?: string;
+    };
+    agent?: {
+        provider?: string;
+        model?: string;
+        confidence_gates?: Array<{
+            threshold?: number;
+        }>;
+        hitl_gates?: Array<Record<string, unknown>>;
+        commitment_chain?: {
+            enabled?: boolean;
+        };
+        signing?: {
+            enabled?: boolean;
+        };
+    };
+    rcan_protocol?: {
+        jwt_auth?: {
+            enabled?: boolean;
+        };
+    };
+    [key: string]: unknown;
+}
+declare function validateConfig(config: RCANConfig): ValidationResult;
+
+/**
+ * RCAN error class hierarchy.
+ * All errors extend RCANError which extends the built-in Error.
+ */
+declare class RCANError extends Error {
+    constructor(message: string);
+}
+declare class RCANAddressError extends RCANError {
+    constructor(message: string);
+}
+declare class RCANValidationError extends RCANError {
+    constructor(message: string);
+}
+declare class RCANGateError extends RCANError {
+    gateType: string;
+    value?: number | undefined;
+    threshold?: number | undefined;
+    constructor(message: string, gateType: string, value?: number | undefined, threshold?: number | undefined);
+}
+declare class RCANSignatureError extends RCANError {
+    constructor(message: string);
+}
+declare class RCANRegistryError extends RCANError {
+    constructor(message: string);
+}
+
+/**
+ * rcan-ts — RegistryClient
+ * TypeScript parity with rcan-py RegistryClient.
+ *
+ * @see https://rcan.dev/spec#section-registry
+ */
+interface RobotRegistration {
+    manufacturer: string;
+    model: string;
+    version: string;
+    device_id: string;
+    description?: string;
+    contact_email?: string;
+    verification_tier?: string;
+    source?: string;
+}
+interface Robot extends RobotRegistration {
+    rrn: string;
+    registered_at: string;
+    updated_at: string;
+    verification_tier: string;
+    status: string;
+}
+interface RegistrationResult {
+    rrn: string;
+    api_key: string;
+}
+interface ListResult {
+    robots: Robot[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+declare class RegistryClient {
+    private baseUrl;
+    private apiKey?;
+    private timeout;
+    constructor(opts?: {
+        baseUrl?: string;
+        apiKey?: string;
+        timeout?: number;
+    });
+    private _fetch;
+    private _authHeaders;
+    private _checkResponse;
+    /** Register a new robot. Returns RRN + API key. */
+    register(robot: RobotRegistration): Promise<RegistrationResult>;
+    /** Look up a robot by RRN. */
+    get(rrn: string): Promise<Robot>;
+    /** List robots with optional pagination and tier filter. */
+    list(opts?: {
+        limit?: number;
+        offset?: number;
+        tier?: string;
+    }): Promise<ListResult>;
+    /** Update robot fields. Requires API key. */
+    patch(rrn: string, updates: Partial<Robot>): Promise<Robot>;
+    /** Delete (soft-delete) a robot. Requires API key. */
+    delete(rrn: string): Promise<void>;
+    /** Search robots by query, manufacturer, model, or tier. */
+    search(opts: {
+        q?: string;
+        manufacturer?: string;
+        model?: string;
+        tier?: string;
+    }): Promise<Robot[]>;
+}
+
+/**
+ * rcan-ts — Official TypeScript SDK for RCAN v1.2
+ * Robot Communication and Accountability Network
+ *
+ * @see https://rcan.dev
+ * @see https://github.com/continuonai/rcan-ts
+ */
+
+declare const VERSION = "0.1.0";
+declare const RCAN_VERSION = "1.2";
+
+export { type ApprovalStatus, AuditChain, AuditError, type ChainVerifyResult, CommitmentRecord, type CommitmentRecordData, type CommitmentRecordJSON, ConfidenceGate, GateError, HiTLGate, type ListResult, type PendingApproval, RCANAddressError, type RCANConfig, RCANError, RCANGateError, RCANMessage, type RCANMessageData, RCANMessageError, RCANRegistryError, RCANSignatureError, RCANValidationError, RCAN_VERSION, type RegistrationResult, RegistryClient, type Robot, type RobotRegistration, RobotURI, RobotURIError, type RobotURIOptions, type SignatureBlock, VERSION, type ValidationResult, validateConfig, validateMessage, validateURI };