contexta-sdk 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# contexta-sdk
+
+Client SDK for **Contexta** — agentic, non-custodial treasury & payroll on Stellar for LATAM.
+
+- **Typed API client** for the Contexta API (treasury, payroll, agent, legal).
+- **Sign In With Stellar** (SEP-53) — wallet-agnostic (Freighter, Stellar Wallets Kit, …).
+- **Legal Context Protocol (LCP)** — re-derive and verify a context's SHA-256 independently.
+
+Isomorphic (browser + Node ≥ 18), ESM, zero server dependencies.
+
+## Install
+
+```bash
+npm i contexta-sdk
+```
+
+## Sign in with a Stellar wallet
+
+```ts
+import { ContextaClient, signInWithStellar } from "contexta-sdk";
+import { StellarWalletsKit, Networks, defaultModules } from "@creit.tech/stellar-wallets-kit";
+
+const client = new ContextaClient({ baseUrl: "https://contexta-api.fly.dev" });
+
+StellarWalletsKit.init({ network: Networks.TESTNET, modules: defaultModules() });
+const { address } = await StellarWalletsKit.authModal();
+
+const session = await signInWithStellar({
+  client,
+  address,
+  signMessage: async (msg) => (await StellarWalletsKit.signMessage(msg, { address })).signedMessage,
+});
+
+// Authenticated, tenant-scoped client:
+const api = client.withSession(session);
+const treasury = await api.treasury();
+const decisions = await api.decisions();
+```
+
+`signMessage` is any function returning the base64 SEP-53 signature, so the SDK
+works with Freighter directly or any wallet adapter.
+
+## Verify a Legal Context independently
+
+```ts
+import { hashLegalContext, verifyLegalContext } from "contexta-sdk";
+
+const doc = await client.wellKnownLegalContext("acme.contexta.app");
+const hash = hashLegalContext(doc); // canonical SHA-256 (hex)
+verifyLegalContext(doc, onChainHashFromEvent); // boolean
+```
+
+The canonicalization is byte-for-byte identical to the Contexta platform, so a
+hash bound into a Soroban event can be re-derived and checked client-side.
+
+## License
+
+Apache-2.0

package/dist/auth.d.ts

@@ -0,0 +1,21 @@
+import type { ContextaClient } from "./client.js";
+import type { WalletSession } from "./types.js";
+/**
+ * A function that signs a SEP-53 message with a Stellar wallet and returns the
+ * base64 signature. Wallet-agnostic — pass an adapter for Freighter, Stellar
+ * Wallets Kit, etc. Example (Stellar Wallets Kit):
+ *
+ *   const signMessage = async (msg) =>
+ *     (await StellarWalletsKit.signMessage(msg, { address })).signedMessage;
+ */
+export type SignMessageFn = (message: string) => Promise<string> | string;
+/**
+ * Sign In With Stellar (SEP-53): request a challenge, have the wallet sign it,
+ * and exchange the signature for a Contexta session JWT.
+ */
+export declare function signInWithStellar(opts: {
+    client: ContextaClient;
+    address: string;
+    signMessage: SignMessageFn;
+}): Promise<WalletSession>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;AAE1E;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,aAAa,CAAC;CAC5B,GAAG,OAAO,CAAC,aAAa,CAAC,CAKzB"}

package/dist/auth.js

@@ -0,0 +1,11 @@
+/**
+ * Sign In With Stellar (SEP-53): request a challenge, have the wallet sign it,
+ * and exchange the signature for a Contexta session JWT.
+ */
+export async function signInWithStellar(opts) {
+    const { client, address, signMessage } = opts;
+    const { message, hmac } = await client.challenge(address);
+    const signedMessage = await signMessage(message);
+    return client.verify({ address, message, hmac, signedMessage });
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAIvC;IACC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAC9C,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC1D,MAAM,aAAa,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;AAClE,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+import type { AgentDecision, LegalContext, LegalState, Obligation, TreasurySnapshot, WalletChallenge, WalletSession } from "./types.js";
+export interface ContextaClientOptions {
+    /** Base URL of the Contexta API, e.g. https://contexta-api.fly.dev */
+    baseUrl: string;
+    /** Session JWT (from wallet sign-in). Required for tenant-scoped endpoints. */
+    accessToken?: string;
+    /** Tenant id to scope requests to (sent as x-tenant-id). */
+    tenantId?: string;
+    /** Custom fetch (defaults to global fetch). */
+    fetch?: typeof fetch;
+}
+/**
+ * Typed client for the Contexta API. Use the unauthenticated handshake
+ * (`challenge`/`verify`, or the `signInWithStellar` helper) to obtain a session,
+ * then `withSession()` to get an authenticated client for tenant-scoped reads.
+ */
+export declare class ContextaClient {
+    private readonly baseUrl;
+    private readonly accessToken?;
+    private readonly tenantId?;
+    private readonly fetchImpl;
+    constructor(options: ContextaClientOptions);
+    /** Return a new client carrying the given session (token + tenant). */
+    withSession(session: Pick<WalletSession, "token" | "tenantId">): ContextaClient;
+    challenge(address: string): Promise<WalletChallenge>;
+    verify(input: {
+        address: string;
+        message: string;
+        hmac: string;
+        signedMessage: string;
+    }): Promise<WalletSession>;
+    treasury(): Promise<TreasurySnapshot>;
+    obligations(): Promise<Obligation[]>;
+    decisions(): Promise<AgentDecision[]>;
+    propose(execute?: boolean): Promise<AgentDecision>;
+    legal(): Promise<LegalState>;
+    /** Fetch a tenant's public legal-context.json (served at the API mirror). */
+    wellKnownLegalContext(domain: string): Promise<LegalContext>;
+    private request;
+}
+export declare class ContextaApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,eAAe,EACf,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE,qBAAqB;IAS1C,uEAAuE;IACvE,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,UAAU,CAAC,GAAG,cAAc;IAU/E,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAIpD,MAAM,CAAC,KAAK,EAAE;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC,aAAa,CAAC;IAK1B,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAIrC,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAIpC,SAAS,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAIrC,OAAO,CAAC,OAAO,UAAQ,GAAG,OAAO,CAAC,aAAa,CAAC;IAIhD,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IAI5B,6EAA6E;IACvE,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;YASpD,OAAO;CA6BtB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;aAEvB,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM;CAKlB"}

package/dist/client.js

@@ -0,0 +1,93 @@
+/**
+ * Typed client for the Contexta API. Use the unauthenticated handshake
+ * (`challenge`/`verify`, or the `signInWithStellar` helper) to obtain a session,
+ * then `withSession()` to get an authenticated client for tenant-scoped reads.
+ */
+export class ContextaClient {
+    baseUrl;
+    accessToken;
+    tenantId;
+    fetchImpl;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.accessToken = options.accessToken;
+        this.tenantId = options.tenantId;
+        const f = options.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new Error("No fetch implementation available; pass options.fetch");
+        this.fetchImpl = f;
+    }
+    /** Return a new client carrying the given session (token + tenant). */
+    withSession(session) {
+        return new ContextaClient({
+            baseUrl: this.baseUrl,
+            accessToken: session.token,
+            tenantId: session.tenantId,
+            fetch: this.fetchImpl,
+        });
+    }
+    // ── Wallet sign-in handshake (no auth) ───────────────────────────────────
+    challenge(address) {
+        return this.request("/auth/wallet/challenge", { method: "POST", body: { address } }, false);
+    }
+    verify(input) {
+        return this.request("/auth/wallet/verify", { method: "POST", body: input }, false);
+    }
+    // ── Tenant-scoped reads (require a session) ──────────────────────────────
+    treasury() {
+        return this.request("/treasury");
+    }
+    obligations() {
+        return this.request("/payroll/obligations");
+    }
+    decisions() {
+        return this.request("/agent/decisions");
+    }
+    propose(execute = false) {
+        return this.request("/agent/propose", { method: "POST", body: { execute } });
+    }
+    legal() {
+        return this.request("/legal");
+    }
+    /** Fetch a tenant's public legal-context.json (served at the API mirror). */
+    async wellKnownLegalContext(domain) {
+        const res = await this.fetchImpl(`${this.baseUrl}/.well-known/legal-context.json?domain=${encodeURIComponent(domain)}`, { headers: { accept: "application/json" } });
+        if (!res.ok)
+            throw new ContextaApiError(res.status, `.well-known -> ${res.status}`);
+        return (await res.json());
+    }
+    async request(path, init = {}, auth = true) {
+        const headers = { "content-type": "application/json" };
+        if (auth) {
+            if (!this.accessToken || !this.tenantId) {
+                throw new Error(`Endpoint ${path} requires a session — call withSession() first`);
+            }
+            headers.authorization = `Bearer ${this.accessToken}`;
+            headers["x-tenant-id"] = this.tenantId;
+        }
+        const res = await this.fetchImpl(`${this.baseUrl}/api/v1${path}`, {
+            method: init.method ?? "GET",
+            headers,
+            body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+        });
+        const text = await res.text();
+        const json = text ? JSON.parse(text) : null;
+        if (!res.ok) {
+            let msg = `API ${path} -> ${res.status}`;
+            if (json && typeof json === "object" && "error" in json) {
+                msg = String(json.error);
+            }
+            throw new ContextaApiError(res.status, msg);
+        }
+        return json;
+    }
+}
+export class ContextaApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "ContextaApiError";
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAqBA;;;;GAIG;AACH,MAAM,OAAO,cAAc;IACR,OAAO,CAAS;IAChB,WAAW,CAAU;IACrB,QAAQ,CAAU;IAClB,SAAS,CAAe;IAEzC,YAAY,OAA8B;QACxC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACnD,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;QAC5C,IAAI,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QACjF,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,uEAAuE;IACvE,WAAW,CAAC,OAAkD;QAC5D,OAAO,IAAI,cAAc,CAAC;YACxB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW,EAAE,OAAO,CAAC,KAAK;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,KAAK,EAAE,IAAI,CAAC,SAAS;SACtB,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,SAAS,CAAC,OAAe;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,wBAAwB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;IAC9F,CAAC;IAED,MAAM,CAAC,KAKN;QACC,OAAO,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,KAAK,CAAC,CAAC;IACrF,CAAC;IAED,4EAA4E;IAC5E,QAAQ;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACnC,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC9C,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,CAAC,OAAO,GAAG,KAAK;QACrB,OAAO,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,qBAAqB,CAAC,MAAc;QACxC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAC9B,GAAG,IAAI,CAAC,OAAO,0CAA0C,kBAAkB,CAAC,MAAM,CAAC,EAAE,EACrF,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,EAAE,CAC5C,CAAC;QACF,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,kBAAkB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACpF,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAiB,CAAC;IAC5C,CAAC;IAEO,KAAK,CAAC,OAAO,CACnB,IAAY,EACZ,OAA4C,EAAE,EAC9C,IAAI,GAAG,IAAI;QAEX,MAAM,OAAO,GAA2B,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;QAC/E,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACxC,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,gDAAgD,CAAC,CAAC;YACpF,CAAC;YACD,OAAO,CAAC,aAAa,GAAG,UAAU,IAAI,CAAC,WAAW,EAAE,CAAC;YACrD,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;QACzC,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,OAAO,UAAU,IAAI,EAAE,EAAE;YAChE,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,KAAK;YAC5B,OAAO;YACP,IAAI,EAAE,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;SACtE,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAa,CAAC,CAAC,CAAC,IAAI,CAAC;QACzD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,IAAI,GAAG,GAAG,OAAO,IAAI,OAAO,GAAG,CAAC,MAAM,EAAE,CAAC;YACzC,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;gBACxD,GAAG,GAAG,MAAM,CAAE,IAA2B,CAAC,KAAK,CAAC,CAAC;YACnD,CAAC;YACD,MAAM,IAAI,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,IAAS,CAAC;IACnB,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAEvB;IADlB,YACkB,MAAc,EAC9B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,WAAM,GAAN,MAAM,CAAQ;QAI9B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { ContextaClient, ContextaApiError, type ContextaClientOptions } from "./client.js";
+export { signInWithStellar, type SignMessageFn } from "./auth.js";
+export { canonicalize, hashLegalContext, verifyLegalContext, legalContextUrl, LCP_WELL_KNOWN_PATH, } from "./lcp.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC3F,OAAO,EAAE,iBAAiB,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,GACpB,MAAM,UAAU,CAAC;AAClB,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { ContextaClient, ContextaApiError } from "./client.js";
+export { signInWithStellar } from "./auth.js";
+export { canonicalize, hashLegalContext, verifyLegalContext, legalContextUrl, LCP_WELL_KNOWN_PATH, } from "./lcp.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAA8B,MAAM,aAAa,CAAC;AAC3F,OAAO,EAAE,iBAAiB,EAAsB,MAAM,WAAW,CAAC;AAClE,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,GACpB,MAAM,UAAU,CAAC;AAClB,cAAc,YAAY,CAAC"}

package/dist/lcp.d.ts

@@ -0,0 +1,18 @@
+import type { LegalContext } from "./types.js";
+/**
+ * Deterministic JSON canonicalization (subset of RFC 8785 / JCS): object keys
+ * sorted, no insignificant whitespace, arrays preserved in order, `undefined`
+ * dropped. Byte-for-byte identical to the Contexta platform so an SDK consumer
+ * can independently re-derive and verify a legal context's SHA-256.
+ */
+export declare function canonicalize(value: unknown): string;
+/** SHA-256 (hex) of a legal context over its canonical JSON form. */
+export declare function hashLegalContext(context: LegalContext): string;
+/**
+ * Verify a legal context document against an expected hash (e.g. one bound into
+ * an on-chain event or returned by the API). Case-insensitive hex compare.
+ */
+export declare function verifyLegalContext(context: LegalContext, expectedHash: string): boolean;
+export declare const LCP_WELL_KNOWN_PATH = "/.well-known/legal-context.json";
+export declare function legalContextUrl(tenantDomain: string): string;
+//# sourceMappingURL=lcp.d.ts.map

package/dist/lcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lcp.d.ts","sourceRoot":"","sources":["../src/lcp.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAmBnD;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAE9D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAEvF;AAED,eAAO,MAAM,mBAAmB,oCAAoC,CAAC;AAErE,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/dist/lcp.js

@@ -0,0 +1,46 @@
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils";
+/**
+ * Deterministic JSON canonicalization (subset of RFC 8785 / JCS): object keys
+ * sorted, no insignificant whitespace, arrays preserved in order, `undefined`
+ * dropped. Byte-for-byte identical to the Contexta platform so an SDK consumer
+ * can independently re-derive and verify a legal context's SHA-256.
+ */
+export function canonicalize(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("Cannot canonicalize non-finite number");
+        return JSON.stringify(value);
+    }
+    if (typeof value === "boolean" || typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalize).join(",")}]`;
+    }
+    if (typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalize(v)}`).join(",")}}`;
+    }
+    throw new Error(`Cannot canonicalize value of type ${typeof value}`);
+}
+/** SHA-256 (hex) of a legal context over its canonical JSON form. */
+export function hashLegalContext(context) {
+    return bytesToHex(sha256(utf8ToBytes(canonicalize(context))));
+}
+/**
+ * Verify a legal context document against an expected hash (e.g. one bound into
+ * an on-chain event or returned by the API). Case-insensitive hex compare.
+ */
+export function verifyLegalContext(context, expectedHash) {
+    return hashLegalContext(context).toLowerCase() === expectedHash.toLowerCase();
+}
+export const LCP_WELL_KNOWN_PATH = "/.well-known/legal-context.json";
+export function legalContextUrl(tenantDomain) {
+    return `https://${tenantDomain}${LCP_WELL_KNOWN_PATH}`;
+}
+//# sourceMappingURL=lcp.js.map

package/dist/lcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lcp.js","sourceRoot":"","sources":["../src/lcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAG9D;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QACtF,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5D,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAClD,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;aAC7D,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC;aAClC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpD,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAC7F,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,qCAAqC,OAAO,KAAK,EAAE,CAAC,CAAC;AACvE,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,gBAAgB,CAAC,OAAqB;IACpD,OAAO,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAqB,EAAE,YAAoB;IAC5E,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,KAAK,YAAY,CAAC,WAAW,EAAE,CAAC;AAChF,CAAC;AAED,MAAM,CAAC,MAAM,mBAAmB,GAAG,iCAAiC,CAAC;AAErE,MAAM,UAAU,eAAe,CAAC,YAAoB;IAClD,OAAO,WAAW,YAAY,GAAG,mBAAmB,EAAE,CAAC;AACzD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+/** Public types for the Contexta SDK. Mirror the API's JSON response shapes. */
+export type Country = "BR" | "AR" | "CO";
+export type Asset = "USDC" | "XLM" | "CETES" | "BRL" | "ARS" | "COP";
+export type Strategy = "liquidity" | "defindex_vault" | "blend_pool";
+export type Rail = "PIX" | "TRANSFERENCIAS_3" | "BRE_B" | "STELLAR" | "SEP24" | "SEP31";
+export interface TreasuryConfig {
+    minLiquidityBaseUnits: string;
+    maxYieldBps: number;
+    volatilitySensitivity: number;
+    countryLimitsBps: Record<string, number>;
+}
+export interface TreasuryPosition {
+    asset: string;
+    strategy: Strategy;
+    strategyRef: string | null;
+    amountBaseUnits: string;
+    apyBps: number | null;
+}
+export interface TreasurySnapshot {
+    config: TreasuryConfig | null;
+    positions: TreasuryPosition[];
+    totals: {
+        liquidBaseUnits: string;
+        yieldBaseUnits: string;
+        totalBaseUnits: string;
+        yieldShareBps: number;
+    };
+}
+export interface Obligation {
+    scheduleId: string;
+    scheduleName: string;
+    nextRunAt: string;
+    asset: string;
+    requiredBaseUnits: string;
+    employeeCount?: number;
+}
+export interface AgentDecision {
+    id: string;
+    action: string;
+    rationale: string;
+    status: string;
+    legalContextHash: string | null;
+    stellarTxHash: string | null;
+    createdAt: string;
+}
+export interface LegalState {
+    published: boolean;
+    hash?: string;
+    document?: LegalContext;
+}
+export interface WalletChallenge {
+    message: string;
+    hmac: string;
+}
+export interface WalletSession {
+    token: string;
+    tokenType: "Bearer";
+    expiresAt: string;
+    address: string;
+    userId: string;
+    tenantId: string;
+    role: string;
+}
+export interface LcpParty {
+    legalName: string;
+    jurisdiction: string;
+    registrationId?: string;
+    contactEmail: string;
+}
+export interface LcpConsentRequirement {
+    id: string;
+    description: string;
+    required: boolean;
+    scope: Array<"treasury" | "payroll" | "yield" | "onramp" | "offramp">;
+}
+export interface LcpDisputeChannel {
+    type: "arbitration" | "mediation" | "court" | "ombudsman";
+    provider: string;
+    venue: string;
+    governingLaw: string;
+    language: string;
+}
+export interface LegalContext {
+    specVersion: string;
+    contextId: string;
+    version: number;
+    tenantDomain: string;
+    provider: LcpParty;
+    terms: {
+        url: string;
+        sha256: string;
+        effectiveDate: string;
+    };
+    jurisdiction: string;
+    consentRequirements: LcpConsentRequirement[];
+    disputeChannels: LcpDisputeChannel[];
+    settlement: {
+        networks: string[];
+        assets: string[];
+    };
+    publishedAt: string;
+}
+/** Compact binding embedded into agentic Stellar transactions. */
+export interface LcpBinding {
+    contextId: string;
+    version: number;
+    hash: string;
+    consents: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,3 @@
+/** Public types for the Contexta SDK. Mirror the API's JSON response shapes. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gFAAgF"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "contexta-sdk",
+  "version": "0.1.0",
+  "description": "Client SDK for Contexta — agentic treasury & payroll on Stellar. Typed API client, Stellar wallet sign-in (SEP-53), and Legal Context Protocol (LCP) hashing/verification.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "stellar",
+    "soroban",
+    "contexta",
+    "sdk",
+    "treasury",
+    "payroll",
+    "lcp",
+    "legal-context-protocol",
+    "freighter",
+    "sep-53",
+    "wallet-auth"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/contexta/contexta",
+    "directory": "packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.6.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint \"src/**/*.ts\"",
+    "test": "vitest run"
+  }
+}