@obscura-fhe/sdk 1.0.1 → 1.0.4

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to `@obscura-fhe/sdk` are documented in this file.
 
+## [1.0.4] - 2026-05-30
+
+### Added
+
+- **AgentModule** — create, list, revoke, and regenerate agent tokens via Obscura API
+- **`agentToken` config** — `Authorization: Bearer` on wallet-scoped API reads
+- **`getAuthenticatedSummary()`** / **`listAuthenticated()`** — `/agent/reputation` and `/agent/activity`
+- **`buildAgentTokenMessage()`** — EIP-191 message helper for token issuance
+
+### Changed
+
+- **HttpClient** sends Bearer header when `agentToken` is set
+- **ReputationModule** / **ActivityModule** route authenticated reads to `/agent/*` when token configured
+
+## [1.0.3] - 2026-05-30
+
+### Changed
+
+- **Activity module:** reads via `GET /activity/:wallet` on Obscura API — no Supabase credentials required
+- **Breaking:** `ActivityModule` constructor now takes `HttpClient` only; `supabaseUrl` / `supabaseAnonKey` config deprecated
+
+## [1.0.2] - 2026-05-30
+
+### Added
+
+- **Credit module:** `getMarketUtilization()` — public pool aggregates (`utilizationBps`, `totalSupplyAssets`, `totalBorrowAssets`)
+- **Credit module:** `getPositionHandles()` — encrypted position handles as opaque hex; optional plaintext shadows with explicit warning
+- Exported types: `CreditMarketUtilization`, `CreditPositionHandles`
+
 ## [1.0.1] - 2026-05-29
 
 ### Fixed

package/dist/index.cjs

@@ -2,7 +2,6 @@
 
 var viem = require('viem');
 var chains = require('viem/chains');
-var supabaseJs = require('@supabase/supabase-js');
 
 // src/config/defaults.ts
 var ARBITRUM_SEPOLIA_CHAIN_ID = 421614;
@@ -68,18 +67,30 @@ function stripTrailingSlash(url) {
 
 // src/core/http.ts
 var HttpClient = class {
-  constructor(baseUrl) {
+  constructor(baseUrl, agentToken) {
     this.baseUrl = baseUrl;
+    this.agentToken = agentToken;
   }
   baseUrl;
+  agentToken;
   get url() {
     return stripTrailingSlash(this.baseUrl);
   }
+  hasAgentToken() {
+    return Boolean(this.agentToken);
+  }
+  authHeaders(extra) {
+    return {
+      Accept: "application/json",
+      ...this.agentToken ? { Authorization: `Bearer ${this.agentToken}` } : {},
+      ...extra
+    };
+  }
   async get(path, init) {
     const response = await fetch(`${this.url}${path}`, {
       ...init,
       method: "GET",
-      headers: { Accept: "application/json", ...init?.headers }
+      headers: this.authHeaders(init?.headers)
     });
     if (!response.ok) {
       const body = await response.text().catch(() => "");
@@ -92,8 +103,9 @@ var HttpClient = class {
       ...init,
       method: "POST",
       headers: {
-        Accept: "application/json",
-        "Content-Type": "application/json",
+        ...this.authHeaders({
+          "Content-Type": "application/json"
+        }),
         ...init?.headers
       },
       body: JSON.stringify(body)
@@ -109,8 +121,9 @@ var HttpClient = class {
       ...init,
       method: "DELETE",
       headers: {
-        Accept: "application/json",
-        "Content-Type": "application/json",
+        ...this.authHeaders({
+          "Content-Type": "application/json"
+        }),
         ...init?.headers
       },
       body: body !== void 0 ? JSON.stringify(body) : void 0
@@ -221,54 +234,115 @@ var ACTIVITY_EVENT_FILTERS = {
 // src/modules/activity.ts
 var DEFAULT_PAGE_SIZE = 20;
 var ActivityModule = class {
-  client;
-  supabaseUrl;
-  supabaseAnonKey;
-  constructor(supabaseUrl, supabaseAnonKey) {
-    this.supabaseUrl = supabaseUrl;
-    this.supabaseAnonKey = supabaseAnonKey;
-    this.client = supabaseUrl && supabaseAnonKey ? supabaseJs.createClient(supabaseUrl, supabaseAnonKey) : null;
-  }
-  /** True when both Supabase URL and anon key were supplied at SDK init. */
+  constructor(http2) {
+    this.http = http2;
+  }
+  http;
+  /** True when API-backed activity reads are available (always when SDK has default apiUrl). */
   isConfigured() {
-    return this.client !== null;
+    return Boolean(this.http.url);
+  }
+  hasAgentToken() {
+    return this.http.hasAgentToken();
   }
   getEventFilters() {
     return ACTIVITY_EVENT_FILTERS;
   }
+  /** Authenticated activity for the agent token wallet */
+  async listAuthenticated(options = {}) {
+    if (!this.http.hasAgentToken()) {
+      throw new Error("agentToken required \u2014 create one at /docs/agents");
+    }
+    return this.listWithPath("/agent/activity", options);
+  }
   async listForWallet(wallet, options = {}) {
-    if (!this.client) {
-      throw new Error(
-        [
-          "Activity module requires Supabase credentials.",
-          `Pass supabaseAnonKey (and optionally supabaseUrl) to ObscuraSDK.create().`,
-          `Default URL: ${DEFAULT_SUPABASE_URL}`,
-          "Get the anon key from your Supabase project \u2192 Settings \u2192 API \u2192 anon public.",
-          "Reputation and notifications work without Supabase; activity does not."
-        ].join(" ")
-      );
+    if (this.http.hasAgentToken()) {
+      return this.listAuthenticated(options);
     }
     const normalized = normalizeWallet(wallet);
     if (!normalized) throw new Error("Invalid wallet address");
+    return this.listWithPath(`/activity/${normalized}`, options);
+  }
+  async listWithPath(basePath, options) {
     const filter = options.filter ?? "all";
     const page = options.page ?? 0;
     const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
-    let query = this.client.from("obscura_activity").select("*").contains("participants", [normalized]).order("block_number", { ascending: false }).range(page * pageSize, page * pageSize + pageSize - 1);
-    const allowed = ACTIVITY_EVENT_FILTERS[filter];
-    if (allowed.length > 0) {
-      query = query.in("event_name", [...allowed]);
+    const params = new URLSearchParams();
+    if (filter !== "all") params.set("filter", filter);
+    if (page > 0) params.set("page", String(page));
+    if (pageSize !== DEFAULT_PAGE_SIZE) params.set("pageSize", String(pageSize));
+    const qs = params.toString();
+    const path = `${basePath}${qs ? `?${qs}` : ""}`;
+    return this.http.get(path);
+  }
+};
+
+// src/modules/agent.ts
+var AgentModule = class {
+  constructor(http2) {
+    this.http = http2;
+  }
+  http;
+  async validateToken(token) {
+    return this.http.post("/agent/validate", { token });
+  }
+  async getIdentity() {
+    if (!this.http.hasAgentToken()) {
+      throw new Error("agentToken required");
     }
-    const { data, error } = await query;
-    if (error) throw new Error(error.message);
-    const items = data ?? [];
-    return {
-      items,
-      page,
-      pageSize,
-      hasMore: items.length === pageSize
-    };
+    return this.http.get("/agent/me");
+  }
+  async createToken(params) {
+    const wallet = normalizeWallet(params.wallet);
+    if (!wallet) throw new Error("Invalid wallet address");
+    return this.http.post("/agent-tokens", {
+      wallet,
+      signature: params.signature,
+      timestamp: params.timestamp,
+      label: params.label,
+      permissions: params.permissions
+    });
+  }
+  async listTokens(params) {
+    const wallet = normalizeWallet(params.wallet);
+    if (!wallet) throw new Error("Invalid wallet address");
+    const qs = new URLSearchParams({
+      wallet,
+      signature: params.signature,
+      timestamp: String(params.timestamp)
+    });
+    return this.http.get(`/agent-tokens?${qs.toString()}`);
+  }
+  async revokeToken(params) {
+    const wallet = normalizeWallet(params.wallet);
+    if (!wallet) throw new Error("Invalid wallet address");
+    return this.http.delete(`/agent-tokens/${params.tokenId}`, {
+      wallet,
+      signature: params.signature,
+      timestamp: params.timestamp
+    });
+  }
+  async regenerateToken(params) {
+    const wallet = normalizeWallet(params.wallet);
+    if (!wallet) throw new Error("Invalid wallet address");
+    return this.http.post(`/agent-tokens/${params.tokenId}/regenerate`, {
+      wallet,
+      signature: params.signature,
+      timestamp: params.timestamp,
+      label: params.label
+    });
   }
 };
+function buildAgentTokenMessage(wallet, timestamp, action, tokenId) {
+  const lines = [
+    "Obscura Agent Token Request",
+    `Wallet: ${wallet.toLowerCase()}`,
+    `Timestamp: ${timestamp}`,
+    `Action: ${action}`
+  ];
+  if (tokenId) lines.push(`TokenId: ${tokenId}`);
+  return lines.join("\n");
+}
 
 // src/abis/index.ts
 var IN_EUINT64_COMPONENTS = [
@@ -317,6 +391,53 @@ var OC_USDC_PAY_ABI = [
   }
 ];
 var CREDIT_MARKET_ABI = [
+  {
+    name: "utilizationBps",
+    type: "function",
+    stateMutability: "view",
+    inputs: [],
+    outputs: [{ name: "", type: "uint256" }]
+  },
+  {
+    name: "totalSupplyAssets",
+    type: "function",
+    stateMutability: "view",
+    inputs: [],
+    outputs: [{ name: "", type: "uint128" }]
+  },
+  {
+    name: "totalBorrowAssets",
+    type: "function",
+    stateMutability: "view",
+    inputs: [],
+    outputs: [{ name: "", type: "uint128" }]
+  },
+  {
+    name: "getPosition",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "user", type: "address" }],
+    outputs: [
+      { name: "encSupplyShares", type: "uint256" },
+      { name: "borrowShares", type: "uint256" },
+      { name: "collateral", type: "uint256" },
+      { name: "disburseTo", type: "uint256" }
+    ]
+  },
+  {
+    name: "getPlainCollateral",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "user", type: "address" }],
+    outputs: [{ name: "", type: "uint128" }]
+  },
+  {
+    name: "getPlainBorrow",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "user", type: "address" }],
+    outputs: [{ name: "", type: "uint128" }]
+  },
   {
     name: "supplyCollateral",
     type: "function",
@@ -389,6 +510,11 @@ var OBSCURA_VOTE_ABI = [
 ];
 
 // src/modules/credit.ts
+var PLAINTEXT_SHADOW_WARNING = "Plaintext shadows are public testnet UI hints only \u2014 not encrypted balances. Do not treat as private position size. Omit on mainnet strict privacy mode.";
+function bigintToHandleHex(value) {
+  const hex = value.toString(16).padStart(64, "0");
+  return `0x${hex}`;
+}
 var CreditModule = class {
   constructor(deps) {
     this.deps = deps;
@@ -397,6 +523,75 @@ var CreditModule = class {
   getMarketAddress(override) {
     return override ?? this.deps.addresses.CreditCanonicalPayOcUSDCMarket;
   }
+  /** Public pool aggregates — no wallet required */
+  async getMarketUtilization(marketAddress) {
+    const market = this.getMarketAddress(marketAddress);
+    const [utilizationBps, totalSupplyAssets, totalBorrowAssets] = await Promise.all([
+      this.deps.publicClient.readContract({
+        address: market,
+        abi: CREDIT_MARKET_ABI,
+        functionName: "utilizationBps"
+      }),
+      this.deps.publicClient.readContract({
+        address: market,
+        abi: CREDIT_MARKET_ABI,
+        functionName: "totalSupplyAssets"
+      }),
+      this.deps.publicClient.readContract({
+        address: market,
+        abi: CREDIT_MARKET_ABI,
+        functionName: "totalBorrowAssets"
+      })
+    ]);
+    return {
+      marketAddress: market,
+      utilizationBps,
+      totalSupplyAssets,
+      totalBorrowAssets
+    };
+  }
+  /**
+   * Returns encrypted position handles as opaque hex strings.
+   * Plaintext shadows are optional and labeled with an explicit warning.
+   */
+  async getPositionHandles(wallet, options = {}) {
+    const normalized = normalizeWallet(wallet);
+    if (!normalized) throw new Error("Invalid wallet address");
+    const market = this.getMarketAddress(options.marketAddress);
+    const position = await this.deps.publicClient.readContract({
+      address: market,
+      abi: CREDIT_MARKET_ABI,
+      functionName: "getPosition",
+      args: [normalized]
+    });
+    const result = {
+      marketAddress: market,
+      wallet: normalized,
+      encryptedSupplySharesHandle: bigintToHandleHex(position[0]),
+      encryptedBorrowSharesHandle: bigintToHandleHex(position[1]),
+      encryptedCollateralHandle: bigintToHandleHex(position[2])
+    };
+    if (options.includePlaintextShadows) {
+      const [plainCollateral, plainBorrow] = await Promise.all([
+        this.deps.publicClient.readContract({
+          address: market,
+          abi: CREDIT_MARKET_ABI,
+          functionName: "getPlainCollateral",
+          args: [normalized]
+        }),
+        this.deps.publicClient.readContract({
+          address: market,
+          abi: CREDIT_MARKET_ABI,
+          functionName: "getPlainBorrow",
+          args: [normalized]
+        })
+      ]);
+      result.plaintextShadowWarning = PLAINTEXT_SHADOW_WARNING;
+      result.plainCollateral = plainCollateral;
+      result.plainBorrow = plainBorrow;
+    }
+    return result;
+  }
   async buildSupplyCollateral(amount, encryptedAmount, marketAddress) {
     const market = this.getMarketAddress(marketAddress);
     const enc = await resolveInEuint64(amount, market, this.deps.fhe, encryptedAmount);
@@ -532,7 +727,24 @@ var ReputationModule = class {
     this.http = http2;
   }
   http;
+  /** True when an agent token is configured for authenticated reads */
+  hasAgentToken() {
+    return this.http.hasAgentToken();
+  }
+  /** Authenticated reputation for the agent token wallet */
+  async getAuthenticatedSummary() {
+    if (!this.http.hasAgentToken()) {
+      throw new Error("agentToken required \u2014 create one at /docs/agents");
+    }
+    return this.http.get("/agent/reputation");
+  }
   async getSummary(wallet) {
+    if (this.http.hasAgentToken()) {
+      return this.getAuthenticatedSummary();
+    }
+    if (!wallet) {
+      throw new Error("Invalid wallet address");
+    }
     const normalized = normalizeWallet(wallet);
     if (!normalized) {
       throw new Error("Invalid wallet address");
@@ -614,6 +826,7 @@ var ObscuraSDK = class _ObscuraSDK {
   vote;
   reputation;
   activity;
+  agent;
   notifications;
   walletClient;
   constructor(config) {
@@ -624,7 +837,7 @@ var ObscuraSDK = class _ObscuraSDK {
     const rpcUrl = config.rpcUrl ?? DEFAULT_RPC_URL;
     this.publicClient = config.publicClient ?? createDefaultPublicClient(rpcUrl, this.chainId);
     const apiUrl = config.apiUrl ?? DEFAULT_API_URL;
-    const http2 = new HttpClient(apiUrl);
+    const http2 = new HttpClient(apiUrl, config.agentToken);
     const moduleDeps = {
       chainId: this.chainId,
       addresses: this.addresses,
@@ -635,15 +848,14 @@ var ObscuraSDK = class _ObscuraSDK {
     this.credit = new CreditModule({
       chainId: this.chainId,
       addresses: this.addresses,
+      publicClient: this.publicClient,
       fhe: this.fhe
     });
     this.vote = new VoteModule(moduleDeps);
     this.reputation = new ReputationModule(http2);
+    this.agent = new AgentModule(http2);
     this.notifications = new NotificationsModule(http2);
-    this.activity = new ActivityModule(
-      config.supabaseUrl ?? DEFAULT_SUPABASE_URL,
-      config.supabaseAnonKey
-    );
+    this.activity = new ActivityModule(http2);
   }
   static create(config = {}) {
     return new _ObscuraSDK(config);
@@ -662,6 +874,7 @@ var ObscuraSDK = class _ObscuraSDK {
 exports.ACTIVITY_EVENT_FILTERS = ACTIVITY_EVENT_FILTERS;
 exports.ARBITRUM_SEPOLIA_CHAIN_ID = ARBITRUM_SEPOLIA_CHAIN_ID;
 exports.ActivityModule = ActivityModule;
+exports.AgentModule = AgentModule;
 exports.CREDIT_MARKET_ABI = CREDIT_MARKET_ABI;
 exports.CreditModule = CreditModule;
 exports.DEFAULT_ADDRESSES = DEFAULT_ADDRESSES;
@@ -677,6 +890,7 @@ exports.ObscuraSDK = ObscuraSDK;
 exports.PayModule = PayModule;
 exports.ReputationModule = ReputationModule;
 exports.VoteModule = VoteModule;
+exports.buildAgentTokenMessage = buildAgentTokenMessage;
 exports.createDefaultPublicClient = createDefaultPublicClient;
 exports.encodeCall = encodeCall;
 exports.normalizeWallet = normalizeWallet;