@greenlandai/sdk 0.1.0

package/src/enyal.js

@@ -0,0 +1,165 @@
+/** client.enyal — full 2.1.0 surface migrated (design §4.1). Citations in JSDoc
+ *  are package-root-relative to published artifacts. */
+import * as cryptoNs from "./core/crypto.js";
+
+export const ENYAL_BASE = "https://api.enyal.ai";
+
+export class EnyalSubmodule {
+  constructor(transport, baseUrl = ENYAL_BASE) {
+    this._t = transport;
+    this._base = baseUrl;
+    this.crypto = cryptoNs; // pure functions incl. deriveSharesFromMnemonic, shamir, node decrypt
+  }
+
+  // ── class A (ENFORCED) ──
+  /** 2.1.0: enyal-client.js:444. */
+  archive({ agentId, chunkType, chunkKey, data, metadata, proofTier, idempotencyKey, retry = true }) {
+    if (typeof data !== "string") data = JSON.stringify(data);
+    const body = { agent_id: agentId, chunk_type: chunkType, chunk_key: chunkKey,
+                   data: Buffer.from(data).toString("base64") };
+    if (metadata) body.metadata = metadata;
+    if (proofTier) body.proof_tier = proofTier;
+    return this._t.request(this._base, "POST", "/api/v1/archive", { body, idempotencyKey, retry });
+  }
+
+  /** 2.1.0: enyal-client.js:499. ENFORCED (G1: trust_routes.py:123-138). */
+  timestamp({ payload, description, idempotencyKey, retry = true }) {
+    if (typeof payload !== "string") payload = JSON.stringify(payload);
+    const body = { payload };
+    if (description) body.description = description;
+    return this._t.request(this._base, "POST", "/api/v1/timestamp", { body, idempotencyKey, retry });
+  }
+
+  /** ENFORCED (G1: trust_routes.py:223-238). */
+  createAgreement({ terms, parties, title, idempotencyKey, retry = true }) {
+    const body = { terms, parties };
+    if (title) body.title = title;
+    return this._t.request(this._base, "POST", "/api/v1/agreement/create", { body, idempotencyKey, retry });
+  }
+
+  /** ENFORCED (G1: trust_routes.py:453-471). */
+  complianceAttest({ periodStart, periodEnd, systems, idempotencyKey, retry = true }) {
+    return this._t.request(this._base, "POST", "/api/v1/compliance/attest",
+      { body: { period_start: periodStart, period_end: periodEnd, systems }, idempotencyKey, retry });
+  }
+
+  // ── class B (ENFORCED) ──
+  /** 2.1.0: enyal-client.js:472. ENFORCED (prove_routes.py:204). */
+  prove({ resourceType, geographicRegion, supplyChainStage, chunkIds, quantumResistant = false,
+          idempotencyKey, retry = true } = {}) {
+    const body = { quantum_resistant: quantumResistant };
+    if (resourceType) body.resource_type = resourceType;
+    if (geographicRegion) body.geographic_region = geographicRegion;
+    if (supplyChainStage) body.supply_chain_stage = supplyChainStage;
+    if (chunkIds) body.chunk_ids = chunkIds;
+    return this._t.request(this._base, "POST", "/api/v1/prove", { body, idempotencyKey, retry });
+  }
+
+  proveBatch({ queries, quantumResistant = true, compress = true, idempotencyKey, retry = true }) {
+    return this._t.request(this._base, "POST", "/api/v1/prove-batch",
+      { body: { queries, quantum_resistant: quantumResistant, compress }, idempotencyKey, retry });
+  }
+
+  /** 2.1.0: enyal-client.js:292. ENFORCED (prove_routes.py:666). */
+  proveShareCombination({ customerShareHex, poseidonKeyHash, idempotencyKey, retry = true }) {
+    const body = { customer_share_hex: customerShareHex };
+    if (poseidonKeyHash) body.poseidon_key_hash = poseidonKeyHash;
+    return this._t.request(this._base, "POST", "/api/v1/prove/share-combination", { body, idempotencyKey, retry });
+  }
+
+  /** 2.1.0: enyal-client.js:483. ENFORCED (disclose_routes.py:274). */
+  disclose({ chunkIds, recipientPubkeyHex, purpose, idempotencyKey, retry = true }) {
+    return this._t.request(this._base, "POST", "/api/v1/disclose",
+      { body: { chunk_ids: chunkIds, recipient_pubkey_hex: recipientPubkeyHex, purpose }, idempotencyKey, retry });
+  }
+
+  /** 2.1.0: enyal-client.js:201. ENFORCED (disclose_routes.py:654). */
+  requestClientDisclosure({ chunkIds, purpose, idempotencyKey, retry = true }) {
+    return this._t.request(this._base, "POST", "/api/v1/disclose/client-side",
+      { body: { chunk_ids: chunkIds, purpose }, idempotencyKey, retry });
+  }
+
+  /** ENFORCED (message_routes.py:312). */
+  sendMessage({ senderAgentId, threadId, recipientAgentId, messageType, payload, idempotencyKey, retry = true }) {
+    return this._t.request(this._base, "POST", "/api/v1/message/send",
+      { body: { sender_agent_id: senderAgentId, thread_id: threadId,
+                recipient_agent_id: recipientAgentId, message_type: messageType, payload },
+        idempotencyKey, retry });
+  }
+
+  getInbox({ agentId, direction = "inbox", ...params } = {}) {
+    return this._t.request(this._base, "GET", "/api/v1/message/inbox",
+      { params: { agent_id: agentId, direction, ...params } });
+  }
+
+  getThread(threadId) {
+    return this._t.request(this._base, "GET", "/api/v1/message/thread/{thread_id}",
+      { pathParams: { thread_id: threadId } });
+  }
+
+  markRead(messageIds, retry = true) {
+    return this._t.request(this._base, "POST", "/api/v1/message/read",
+      { body: { message_ids: messageIds }, retry });
+  }
+
+  // ── reads ──
+  search(params = {}) { return this._t.request(this._base, "GET", "/api/v1/search", { params }); }
+  verifyAgreement({ agreementChunkId, terms }) {
+    return this._t.request(this._base, "POST", "/api/v1/agreement/verify",
+      { body: { agreement_chunk_id: agreementChunkId, terms } });
+  }
+  getLineage(chunkId) {
+    return this._t.request(this._base, "GET", "/api/v1/lineage/{chunk_id}", { pathParams: { chunk_id: chunkId } });
+  }
+  getKnowledgeNodes(params = {}) { return this._t.request(this._base, "GET", "/api/v1/knowledge/nodes", { params }); }
+  getKnowledgeNode(nodeId) {
+    return this._t.request(this._base, "GET", "/api/v1/knowledge/node/{node_id}", { pathParams: { node_id: nodeId } });
+  }
+  getKnowledgeConnections(nodeId, hops = 2) {
+    return this._t.request(this._base, "GET", "/api/v1/knowledge/node/{node_id}/connections",
+      { pathParams: { node_id: nodeId }, params: { hops } });
+  }
+  getContradictions() { return this._t.request(this._base, "GET", "/api/v1/knowledge/contradictions", {}); }
+  getKnowledgeStats() { return this._t.request(this._base, "GET", "/api/v1/knowledge/stats", {}); }
+  getKnowledgeIndex() { return this._t.request(this._base, "GET", "/api/v1/knowledge/index", {}); }
+  getKnowledgeHealth() { return this._t.request(this._base, "GET", "/api/v1/knowledge/health", {}); }
+
+  /** Absorbed stray (AUDIT.6: index.js:342). */
+  getContext({ depth = 1, topic, format = "json" } = {}) {
+    const params = { depth, format };
+    if (topic) params.topic = topic;
+    return this._t.request(this._base, "GET", "/api/v1/knowledge/context", { params });
+  }
+
+  /** Session-auth only — raise-stub preserved per 2.1.0 + design §6. */
+  synthesiseKnowledge() {
+    throw new Error("knowledge/synthesise requires session auth (not API key). Use the ENYAL web console at enyal.ai.");
+  }
+
+  // ── NOT SUPPORTED tier (auto-retry OFF at wrapper) ──
+  /** NOT retry-safe (knowledge_routes.py:448 — 500j billed, no server idempotency). */
+  knowledgeUpgrade(body = {}) { return this._t.request(this._base, "POST", "/api/v1/knowledge/upgrade", { body }); }
+  /** NOT retry-safe (knowledge_routes.py:1337). */
+  memoryStructuredQuery(body = {}) { return this._t.request(this._base, "POST", "/api/v1/memory/structured-query", { body }); }
+  /** NOT retry-safe (knowledge_routes.py:1374). */
+  memoryContentQuery(body = {}) { return this._t.request(this._base, "POST", "/api/v1/memory/content-query", { body }); }
+  /** NOT retry-safe (archive_routes.py:440). */
+  queueProof(chunkId, quantumResistant = false) {
+    return this._t.request(this._base, "POST", "/api/v1/proof/queue",
+      { body: { chunk_id: chunkId, quantum_resistant: quantumResistant } });
+  }
+
+  // ── recovery round-trip (design §4.1.3; wrapped-master-key invariant) ──
+  async recoverFromRecoveryFile(recoveryFile, mnemonic, passphrase = "") {
+    if (typeof recoveryFile === "string") recoveryFile = JSON.parse(recoveryFile);
+    const { customerShare } = cryptoNs.deriveSharesFromMnemonic(mnemonic, passphrase);
+    const custodial = cryptoNs.hexToBytes(recoveryFile.custodial_share_hex);
+    return cryptoNs.combineSharesAndDecrypt(customerShare, custodial, recoveryFile.encrypted_payload);
+  }
+
+  // ── Arch-3 stubs (design §4.1.4 — activate when render phases B-D ship) ──
+  memoryQuery() { throw new Error("NotImplemented: Render phases B-D not yet deployed (Arch-3, REV15-7)"); }
+  executePlan() { throw new Error("NotImplemented: Render phases B-D not yet deployed (Arch-3, REV15-7)"); }
+  renderNode() { throw new Error("NotImplemented: Render phases B-D not yet deployed (Arch-3, REV15-7)"); }
+  renderContext() { throw new Error("NotImplemented: Render phases B-D not yet deployed (Arch-3, REV15-7)"); }
+}

package/src/gldai.js

@@ -0,0 +1,40 @@
+/** client.gldai — intelligence query surface (design §4.4; enumerated at BUILD
+ *  2026-06-10 from api.py route registrations :692-:1221, read-only). Class C
+ *  metering middleware-side (rate_limiter.py:256 -> joule_metering). */
+export const GLDAI_BASE = "https://greenlandai.ai";
+
+export class GldaiSubmodule {
+  constructor(transport, baseUrl = GLDAI_BASE) {
+    this._t = transport; this._base = baseUrl;
+  }
+  companies({ idempotencyKey, ...params } = {}) {
+    return this._t.request(this._base, "GET", "/api/v1/companies", { params, idempotencyKey });
+  }
+  company(companyId) {
+    return this._t.request(this._base, "GET", "/api/v1/companies/{cid}", { pathParams: { cid: companyId } });
+  }
+  deposits({ idempotencyKey, ...params } = {}) {
+    return this._t.request(this._base, "GET", "/api/v1/deposits", { params, idempotencyKey });
+  }
+  deposit(depositId) {
+    return this._t.request(this._base, "GET", "/api/v1/deposits/{did}", { pathParams: { did: depositId } });
+  }
+  infrastructureList({ idempotencyKey, ...params } = {}) {
+    return this._t.request(this._base, "GET", "/api/v1/infrastructure", { params, idempotencyKey });
+  }
+  infrastructure(infraId) {
+    return this._t.request(this._base, "GET", "/api/v1/infrastructure/{iid}", { pathParams: { iid: infraId } });
+  }
+  query(q, { idempotencyKey, ...params } = {}) {
+    return this._t.request(this._base, "GET", "/api/v1/query", { params: { q, ...params }, idempotencyKey });
+  }
+  projects({ idempotencyKey, ...params } = {}) {
+    return this._t.request(this._base, "GET", "/api/v1/projects", { params, idempotencyKey });
+  }
+  project(projectId) {
+    return this._t.request(this._base, "GET", "/api/v1/projects/{pid}", { pathParams: { pid: projectId } });
+  }
+  mapdata({ idempotencyKey, ...params } = {}) {
+    return this._t.request(this._base, "GET", "/api/v1/mapdata", { params, idempotencyKey });
+  }
+}

package/src/joulepai.js

@@ -0,0 +1,116 @@
+/** client.joulepai — 17-method Wallet absorb (design §4.2; AUDIT.6).
+ *  Source-of-record: local joulepai-sdk-js/index.js (never published).
+ *  Transfer-class now carries Class-D keys via dispatch (the local SDK sent none). */
+export const JOULEPAI_BASE = "https://joulepai.ai/api/v1";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export class JoulepaiSubmodule {
+  constructor(transport, baseUrl = JOULEPAI_BASE) {
+    this._t = transport;
+    this._base = baseUrl;
+    this._walletId = null;
+  }
+
+  async _ensureId() {
+    if (!this._walletId) {
+      this._walletId = (await this._t.request(this._base, "GET", "/wallet/me", {})).id;
+    }
+    return this._walletId;
+  }
+
+  /** Absorbs Wallet.create (index.js:50). */
+  createWallet({ email, ownerId, ownerType = "human", handle }) {
+    const body = { owner_id: ownerId || crypto.randomUUID(), owner_type: ownerType, email };
+    if (handle) body.handle = handle;
+    return this._t.request(this._base, "POST", "/wallet/create", { body });
+  }
+
+  /** Absorbs pay() (index.js:117). ENFORCED class D — dispatch auto-generates the key. */
+  async transfer(destination, amount, { platform = "rareeai", note, privacyMode,
+                                        idempotencyKey, retry = true } = {}) {
+    const body = { from_wallet_id: await this._ensureId(), amount, platform };
+    const dest = destination.replace(/^@/, "");
+    body[UUID_RE.test(dest) ? "to_wallet_id" : "to_handle"] = dest;
+    if (note != null) body.note = note;
+    if (privacyMode != null) body.privacy_mode = privacyMode;
+    return this._t.request(this._base, "POST", "/wallet/transfer", { body, idempotencyKey, retry });
+  }
+
+  pay(...args) { return this.transfer(...args); }
+
+  transferStatus(transferId) {
+    return this._t.request(this._base, "GET", "/wallet/transfer/{tid}/status", { pathParams: { tid: transferId } });
+  }
+
+  /** Absorbs fund() (index.js:152). NOT retry-safe (G1 demotion — duplicate Stripe sessions). */
+  async fund(amountFiat, { method = "stripe" } = {}) {
+    return this._t.request(this._base, "POST", "/wallet/fund",
+      { body: { wallet_id: await this._ensureId(), amount_fiat: amountFiat, method } });
+  }
+
+  async balance() {
+    return (await this._t.request(this._base, "GET", "/wallet/balance/{wid}",
+      { pathParams: { wid: await this._ensureId() } })).balance;
+  }
+
+  async info() {
+    return this._t.request(this._base, "GET", "/wallet/balance/{wid}",
+      { pathParams: { wid: await this._ensureId() } });
+  }
+
+  async handle() { return (await this.info()).handle ?? null; }
+
+  async transactions({ limit = 50, offset = 0 } = {}) {
+    return this._t.request(this._base, "GET", "/wallet/transactions/{wid}",
+      { pathParams: { wid: await this._ensureId() }, params: { limit, offset } });
+  }
+
+  async setHandle(h) {
+    return this._t.request(this._base, "PUT", "/wallet/handle",
+      { body: { wallet_id: await this._ensureId(), handle: h.replace(/^@/, "") } });
+  }
+
+  async exchangeRate(currency = "EUR") {
+    return (await this._t.request(this._base, "GET", "/wallet/exchange-rate/{cur}",
+      { pathParams: { cur: currency.toUpperCase() } })).joules_per_unit;
+  }
+
+  async getLimits() {
+    return this._t.request(this._base, "GET", "/wallet/limits/{wid}",
+      { pathParams: { wid: await this._ensureId() } });
+  }
+
+  async setLimits({ daily, perTransaction, allowedPlatforms } = {}) {
+    const body = { agent_wallet_id: await this._ensureId() };
+    if (daily != null) body.daily_cap = daily;
+    if (perTransaction != null) body.per_transaction_cap = perTransaction;
+    if (allowedPlatforms != null) body.allowed_platforms = allowedPlatforms;
+    return this._t.request(this._base, "PUT", "/wallet/limits", { body });
+  }
+
+  async depositInfo() {
+    return this._t.request(this._base, "GET", "/wallet/deposit-info/{wid}",
+      { pathParams: { wid: await this._ensureId() } });
+  }
+
+  depositAddress() { return this._t.request(this._base, "GET", "/wallet/deposit-address", {}); }
+
+  fundingStatus(fundingEventId) {
+    return this._t.request(this._base, "GET", "/wallet/fund/{fid}", { pathParams: { fid: fundingEventId } });
+  }
+
+  resetCredentials(walletId, email) {
+    return this._t.request(this._base, "POST", "/wallet/reset-credentials",
+      { body: { wallet_id: walletId, email } });
+  }
+
+  verify(transactionId) {
+    return this._t.request(this._base, "GET", "/wallet/transaction/{tid}", { pathParams: { tid: transactionId } });
+  }
+
+  async verifyPayment(transactionId, expectedAmount, recipient) {
+    return (await this._t.request(this._base, "POST", "/wallet/verify-payment",
+      { params: { transaction_id: transactionId, expected_amount: expectedAmount, recipient } })).verified;
+  }
+}

package/src/rareeai.js

@@ -0,0 +1,66 @@
+/** client.rareeai — RAREEAI marketplace (single entry point).
+ *  Collapsed 2026-06-10 (WS-2, audit Decision 1) from the prior dual
+ *  `.direct`/`.intelligence` sub-namespaces. Empirical reality (P-DAY.26 audit
+ *  LAYER 1-4): ONE marketplace backend, reachable ONLY via the JoulePAI
+ *  marketplace_proxy at `/api/v1/marketplace/*`. The prior `.direct`
+ *  (`/api/v1`) path did NOT reach rareeai. Fee is a single flat 0.5%
+ *  (config.MATCH_FEE_RATE = 0.005), fixed by ROUTE, never by a parameter.
+ *
+ *  Forward compatibility: a future SECOND entry point (PoolGap tiered-fee
+ *  design) is added as a NEW sub-namespace in an additive MINOR version,
+ *  never a breaking rename. See design §4.3 "Forward Compatibility". */
+export const RAREEAI_BASE = "https://joulepai.ai";   // via JoulePAI marketplace_proxy
+const RAREEAI_PREFIX = "/api/v1/marketplace";          // the ONLY route that reaches rareeai
+
+export class RareeaiSubmodule {
+  constructor(transport, baseUrl = RAREEAI_BASE) {
+    this._t = transport; this._base = baseUrl; this._p = RAREEAI_PREFIX;
+  }
+
+  // Pattern B
+  createProvider({ resourceType, capacity, idempotencyKey, retry = true, ...fields }) {
+    const body = { resource_type: resourceType, ...fields };
+    if (capacity) body.capacity = capacity;
+    return this._t.request(this._base, "POST", `${this._p}/provide`, { body, idempotencyKey, retry });
+  }
+  // ENFORCED-WHEN-PRESENT / BEST-EFFORT-keyless (routes.py:1282 guard; SDK dispatch
+  // always auto-gens a key → SDK callers effectively enforced; keyless gap raw-HTTP-only).
+  createRequest({ resourceType, idempotencyKey, retry = true, ...fields }) {
+    return this._t.request(this._base, "POST", `${this._p}/request`,
+      { body: { resource_type: resourceType, ...fields }, idempotencyKey, retry });
+  }
+  deliver(matchId, { idempotencyKey, retry = true, ...fields } = {}) {
+    return this._t.request(this._base, "POST", `${this._p}/deliver/{match_id}`,
+      { pathParams: { match_id: matchId }, body: fields, idempotencyKey, retry });
+  }
+  resolve(matchId, { idempotencyKey, retry = true, ...fields } = {}) {
+    return this._t.request(this._base, "POST", `${this._p}/match/{match_id}/resolve`,
+      { pathParams: { match_id: matchId }, body: fields, idempotencyKey, retry });
+  }
+
+  // FSM transitions — NOT SUPPORTED (auto-retry OFF)
+  approve(matchId, fields = {}) {
+    return this._t.request(this._base, "POST", `${this._p}/match/{match_id}/approve`,
+      { pathParams: { match_id: matchId }, body: fields });
+  }
+  reject(matchId, fields = {}) {
+    return this._t.request(this._base, "POST", `${this._p}/match/{match_id}/reject`,
+      { pathParams: { match_id: matchId }, body: fields });
+  }
+  dispute(matchId, fields = {}) {
+    return this._t.request(this._base, "POST", `${this._p}/match/{match_id}/dispute`,
+      { pathParams: { match_id: matchId }, body: fields });
+  }
+  extendDispute(matchId, fields = {}) {
+    return this._t.request(this._base, "POST", `${this._p}/match/{match_id}/extend-dispute`,
+      { pathParams: { match_id: matchId }, body: fields });
+  }
+
+  // reads
+  providers(params = {}) { return this._t.request(this._base, "GET", `${this._p}/providers`, { params }); }
+  myProviders() { return this._t.request(this._base, "GET", `${this._p}/providers/mine`, {}); }
+  getRequest(requestId) {
+    return this._t.request(this._base, "GET", `${this._p}/request/{request_id}`,
+      { pathParams: { request_id: requestId } });
+  }
+}