@elsoul/erpc-sdk 0.1.0 → 0.3.0

package/README.md

@@ -48,6 +48,7 @@ network request.
 | `erpc.ethereum.subscriptions` | Ethereum WebSocket subscriptions |
 | `erpc.price` | Price metadata, updates, and streams |
 | `erpc.account` | ERPC token balance |
+| `erpc.usage` | Masked monthly API-key usage |
 
 ## Examples
 
@@ -72,6 +73,33 @@ await heads.unsubscribe()
 erpc.close()
 ```
 
+Monthly API-key usage is available from the same client:
+
+```ts
+const usage = await erpc.usage.getMonthlyApiKeyUsage({
+  yearMonth: '2026-08',
+})
+```
+
+For scoped ERPC Cloud OAuth access tokens, create a client that cannot receive
+or retain refresh credentials:
+
+```ts
+import { createErpcCloudClient } from '@elsoul/erpc-sdk'
+
+const cloud = createErpcCloudClient({ accessToken })
+const catalog = await cloud.catalog.list()
+const credit = await cloud.credit.get()
+const resources = await cloud.resources.list()
+const first = resources[0]
+const status = first ? await cloud.resources.getStatus(first.id) : undefined
+const monthlyUsage = await cloud.usage.getMonthlyApiKeyUsage()
+```
+
+Catalog, credit, and resource results are projected onto documented public
+fields. Interactive login and operating-system keychain storage belong to
+`@elsoul/erpc-cli`.
+
 ## Raw methods
 
 The typed catalogs track methods available from ERPC. The raw API provides

package/dist/index.cjs

@@ -242,9 +242,82 @@ var AccountClient = class {
   }
 };
 
+// src/catalog.ts
+var resourceKinds = [
+  "bare-metal",
+  "solana-grpc",
+  "solana-shredstream",
+  "vps"
+];
+var resourceModes = [
+  "dedicated",
+  "direct",
+  "shared"
+];
+var objectValue = (value) => typeof value === "object" && value !== null ? value : null;
+var stringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string") ? value : null;
+var parseOffering = (value) => {
+  const offering = objectValue(value);
+  if (offering === null || typeof offering.id !== "string" || typeof offering.kind !== "string" || !resourceKinds.includes(offering.kind) || typeof offering.name !== "string" || typeof offering.description !== "string" || offering.mode !== void 0 && (typeof offering.mode !== "string" || !resourceModes.includes(offering.mode))) return null;
+  const regions = stringArray(offering.regions);
+  const capabilities = stringArray(offering.capabilities);
+  if (regions === null || capabilities === null) return null;
+  const compute = offering.compute === void 0 ? void 0 : objectValue(offering.compute);
+  if (compute !== void 0 && (compute === null || compute.tenancy !== "virtual-machine" && compute.tenancy !== "bare-metal")) return null;
+  const solana = offering.solana === void 0 ? void 0 : objectValue(offering.solana);
+  if (solana !== void 0 && (solana === null || solana.transport !== "grpc" && solana.transport !== "shredstream")) return null;
+  const billing = offering.billing === void 0 ? void 0 : objectValue(offering.billing);
+  if (billing !== void 0 && (billing === null || billing.unit !== "cents-per-hour" || typeof billing.amountCents !== "number" || !Number.isInteger(billing.amountCents) || billing.amountCents < 0)) return null;
+  return {
+    id: offering.id,
+    kind: offering.kind,
+    name: offering.name,
+    description: offering.description,
+    regions,
+    capabilities,
+    ...typeof offering.mode === "string" ? { mode: offering.mode } : {},
+    ...compute && (compute.tenancy === "virtual-machine" || compute.tenancy === "bare-metal") ? { compute: { tenancy: compute.tenancy } } : {},
+    ...solana && (solana.transport === "grpc" || solana.transport === "shredstream") ? { solana: { transport: solana.transport } } : {},
+    ...billing && billing.unit === "cents-per-hour" && typeof billing.amountCents === "number" ? {
+      billing: {
+        amountCents: billing.amountCents,
+        unit: billing.unit
+      }
+    } : {}
+  };
+};
+var CloudCatalogClient = class {
+  #transport;
+  constructor(transport) {
+    this.#transport = transport;
+  }
+  async list(options) {
+    const response = await this.#transport.get(
+      "/v4/cloud/catalog",
+      void 0,
+      options
+    );
+    const envelope = objectValue(response);
+    const message = objectValue(envelope?.message);
+    if (envelope?.success !== true || !Array.isArray(message?.offerings)) {
+      throw new ErpcInvalidResponseError(
+        "ERPC returned an invalid Cloud catalog"
+      );
+    }
+    const offerings = message.offerings.map(parseOffering);
+    if (offerings.some((offering) => offering === null)) {
+      throw new ErpcInvalidResponseError(
+        "ERPC returned an invalid Cloud catalog"
+      );
+    }
+    return offerings;
+  }
+};
+
 // src/config.ts
 var DEFAULT_ENDPOINT = "https://edge.erpc.global";
 var DEFAULT_ACCOUNT_ENDPOINT = "https://solana-rpc.erpc.global";
+var DEFAULT_USER_ENDPOINT = "https://user-api.erpc.global";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var requireFetch = (provided) => {
   const implementation = provided ?? globalThis.fetch;
@@ -260,11 +333,13 @@ var resolveConfig = (config) => {
   if (!apiKey) throw new ErpcConfigError("apiKey must not be empty");
   let endpoint;
   let accountEndpoint;
+  let userEndpoint;
   try {
     endpoint = new URL(config.endpoint ?? DEFAULT_ENDPOINT);
     accountEndpoint = new URL(
       config.accountEndpoint ?? DEFAULT_ACCOUNT_ENDPOINT
     );
+    userEndpoint = new URL(config.userEndpoint ?? DEFAULT_USER_ENDPOINT);
   } catch {
     throw new ErpcConfigError("endpoint must be an absolute HTTP(S) URL");
   }
@@ -274,12 +349,18 @@ var resolveConfig = (config) => {
   if (accountEndpoint.protocol !== "https:" && accountEndpoint.protocol !== "http:") {
     throw new ErpcConfigError("accountEndpoint must use HTTP or HTTPS");
   }
+  if (userEndpoint.protocol !== "https:" && userEndpoint.protocol !== "http:") {
+    throw new ErpcConfigError("userEndpoint must use HTTP or HTTPS");
+  }
   endpoint.search = "";
   endpoint.hash = "";
   endpoint.pathname = endpoint.pathname.replace(/\/+$/, "") || "/";
   accountEndpoint.search = "";
   accountEndpoint.hash = "";
   accountEndpoint.pathname = accountEndpoint.pathname.replace(/\/+$/, "") || "/";
+  userEndpoint.search = "";
+  userEndpoint.hash = "";
+  userEndpoint.pathname = userEndpoint.pathname.replace(/\/+$/, "") || "/";
   const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
     throw new ErpcConfigError("timeoutMs must be a positive finite number");
@@ -291,6 +372,7 @@ var resolveConfig = (config) => {
     fetch: requireFetch(config.fetch),
     headers: config.headers ?? {},
     timeoutMs,
+    userEndpoint,
     ...config.webSocket === void 0 ? {} : { webSocket: config.webSocket }
   };
 };
@@ -1123,6 +1205,7 @@ var HttpJsonRpcTransport = class {
       }
       throw new ErpcInvalidResponseError("ERPC returned a non-array batch response");
     }
+    const expectedIds = new Set(requests.map((request) => request.id));
     const byId = /* @__PURE__ */ new Map();
     for (const response of raw) {
       if (!isObject2(response) || !("id" in response)) {
@@ -1132,6 +1215,16 @@ var HttpJsonRpcTransport = class {
       if (typeof id !== "number" && typeof id !== "string") {
         throw new ErpcInvalidResponseError("ERPC returned an invalid batch id");
       }
+      if (!expectedIds.has(id)) {
+        throw new ErpcInvalidResponseError(
+          "ERPC returned an unexpected batch response id"
+        );
+      }
+      if (byId.has(id)) {
+        throw new ErpcInvalidResponseError(
+          `ERPC returned duplicate batch response id ${String(id)}`
+        );
+      }
       byId.set(id, response);
     }
     const results = requests.map((request) => {
@@ -1198,6 +1291,91 @@ var HttpJsonRpcTransport = class {
   }
 };
 
+// src/usage.ts
+var YEAR_MONTH = /^\d{4}-(0[1-9]|1[0-2])$/;
+var objectValue2 = (value) => typeof value === "object" && value !== null ? value : null;
+var isTimestamp = (value) => value === null || typeof value === "string";
+var parseMethod = (value) => {
+  const method = objectValue2(value);
+  if (method === null || typeof method.count !== "number" || typeof method.creditCost !== "number" || typeof method.credits !== "number" || typeof method.method !== "string" || !isTimestamp(method.updatedAt)) return null;
+  return {
+    count: method.count,
+    creditCost: method.creditCost,
+    credits: method.credits,
+    method: method.method,
+    updatedAt: method.updatedAt
+  };
+};
+var parseChain = (value) => {
+  const chain = objectValue2(value);
+  if (chain === null || typeof chain.chain !== "string" || typeof chain.count !== "number" || typeof chain.credits !== "number" || !Array.isArray(chain.methods) || !isTimestamp(chain.updatedAt)) return null;
+  const methods = chain.methods.map(parseMethod);
+  if (methods.some((method) => method === null)) return null;
+  return {
+    chain: chain.chain,
+    count: chain.count,
+    credits: chain.credits,
+    methods,
+    updatedAt: chain.updatedAt
+  };
+};
+var parseApiKey = (value) => {
+  const apiKey = objectValue2(value);
+  if (apiKey === null || typeof apiKey.apiKeyLast4 !== "string" || typeof apiKey.apiKeyLength !== "number" || !Array.isArray(apiKey.chains) || typeof apiKey.count !== "number" || typeof apiKey.credits !== "number" || apiKey.keyId !== null && typeof apiKey.keyId !== "number" || !isTimestamp(apiKey.updatedAt)) return null;
+  const chains = apiKey.chains.map(parseChain);
+  if (chains.some((chain) => chain === null)) return null;
+  return {
+    apiKeyLast4: apiKey.apiKeyLast4,
+    apiKeyLength: apiKey.apiKeyLength,
+    chains,
+    count: apiKey.count,
+    credits: apiKey.credits,
+    keyId: apiKey.keyId,
+    updatedAt: apiKey.updatedAt
+  };
+};
+var parseMonthlyUsage = (value) => {
+  const usage = objectValue2(value);
+  if (usage === null || !Array.isArray(usage.apiKeys) || !Array.isArray(usage.chains) || typeof usage.hasStrandedUsage !== "boolean" || typeof usage.keyCount !== "number" || typeof usage.totalCount !== "number" || typeof usage.totalCredits !== "number" || !isTimestamp(usage.updatedAt) || typeof usage.yearMonth !== "string" || !YEAR_MONTH.test(usage.yearMonth)) return null;
+  const apiKeys = usage.apiKeys.map(parseApiKey);
+  const chains = usage.chains.map(parseChain);
+  if (apiKeys.some((apiKey) => apiKey === null) || chains.some((chain) => chain === null)) return null;
+  return {
+    apiKeys,
+    chains,
+    hasStrandedUsage: usage.hasStrandedUsage,
+    keyCount: usage.keyCount,
+    totalCount: usage.totalCount,
+    totalCredits: usage.totalCredits,
+    updatedAt: usage.updatedAt,
+    yearMonth: usage.yearMonth
+  };
+};
+var UsageClient = class {
+  #transport;
+  constructor(transport) {
+    this.#transport = transport;
+  }
+  async getMonthlyApiKeyUsage(params = {}, options) {
+    if (params.yearMonth !== void 0 && !YEAR_MONTH.test(params.yearMonth)) {
+      throw new ErpcConfigError("yearMonth must use YYYY-MM format");
+    }
+    const response = await this.#transport.get(
+      "/v3/user/api-keys/usage",
+      { yearMonth: params.yearMonth },
+      options
+    );
+    const envelope = objectValue2(response);
+    const usage = envelope?.success === true ? parseMonthlyUsage(envelope.message) : null;
+    if (usage === null) {
+      throw new ErpcInvalidResponseError(
+        "ERPC returned an invalid monthly API key usage response"
+      );
+    }
+    return usage;
+  }
+};
+
 // src/client.ts
 var createErpcClient = (config) => {
   const resolved = resolveConfig(config);
@@ -1234,6 +1412,10 @@ var createErpcClient = (config) => {
     ...sharedTransport,
     endpoint: resolved.accountEndpoint
   });
+  const userTransport = new RestTransport({
+    ...sharedTransport,
+    endpoint: resolved.userEndpoint
+  });
   const solana = {
     ...createSolanaClient(solanaTransport),
     subscriptions: new SolanaSubscriptions(solanaWebSocket)
@@ -1247,6 +1429,7 @@ var createErpcClient = (config) => {
     ethereum,
     price: new PriceClient(priceTransport),
     account: new AccountClient(accountTransport),
+    usage: new UsageClient(userTransport),
     close: () => {
       solana.subscriptions.close();
       ethereum.subscriptions.close();
@@ -1254,10 +1437,230 @@ var createErpcClient = (config) => {
   };
 };
 
+// src/credit.ts
+var alertLevels = [
+  "critical",
+  "normal",
+  "suspended",
+  "warning"
+];
+var objectValue3 = (value) => typeof value === "object" && value !== null ? value : null;
+var isDateTime = (value) => typeof value === "string" && Number.isFinite(Date.parse(value));
+var parseCredit = (value) => {
+  const credit = objectValue3(value);
+  if (credit === null || typeof credit.balanceCents !== "number" || !Number.isInteger(credit.balanceCents) || typeof credit.burnRateCentsPerHour !== "number" || !Number.isInteger(credit.burnRateCentsPerHour) || credit.burnRateCentsPerHour < 0 || credit.timeToZeroHours !== null && (typeof credit.timeToZeroHours !== "number" || !Number.isFinite(credit.timeToZeroHours) || credit.timeToZeroHours < 0) || typeof credit.alertLevel !== "string" || !alertLevels.includes(credit.alertLevel) || !isDateTime(credit.quoteTimestamp) || !isDateTime(credit.quoteExpiresAt)) return null;
+  return {
+    alertLevel: credit.alertLevel,
+    balanceCents: credit.balanceCents,
+    burnRateCentsPerHour: credit.burnRateCentsPerHour,
+    quoteExpiresAt: credit.quoteExpiresAt,
+    quoteTimestamp: credit.quoteTimestamp,
+    timeToZeroHours: credit.timeToZeroHours
+  };
+};
+var CloudCreditClient = class {
+  #transport;
+  constructor(transport) {
+    this.#transport = transport;
+  }
+  async get(options) {
+    const response = await this.#transport.get(
+      "/v4/cloud/credit",
+      void 0,
+      options
+    );
+    const envelope = objectValue3(response);
+    const credit = envelope?.success === true ? parseCredit(envelope.message) : null;
+    if (credit === null) {
+      throw new ErpcInvalidResponseError(
+        "ERPC returned an invalid Cloud credit snapshot"
+      );
+    }
+    return credit;
+  }
+};
+
+// src/resources.ts
+var objectValue4 = (value) => typeof value === "object" && value !== null ? value : null;
+var resourceKinds2 = [
+  "bare-metal",
+  "solana-grpc",
+  "solana-shredstream",
+  "vps"
+];
+var resourceModes2 = [
+  "dedicated",
+  "direct",
+  "shared"
+];
+var billingStatuses = [
+  "active",
+  "grace-period",
+  "inactive",
+  "suspended"
+];
+var isDateTime2 = (value) => typeof value === "string" && Number.isFinite(Date.parse(value));
+var parseStatusBilling = (value) => {
+  const billing = objectValue4(value);
+  if (billing === null || typeof billing.status !== "string" || !billingStatuses.includes(
+    billing.status
+  ) || billing.hourlyCredits !== void 0 && (typeof billing.hourlyCredits !== "number" || !Number.isFinite(billing.hourlyCredits) || billing.hourlyCredits < 0) || billing.nextChargeAt !== void 0 && !isDateTime2(billing.nextChargeAt) || billing.graceEndsAt !== void 0 && !isDateTime2(billing.graceEndsAt)) return null;
+  return {
+    status: billing.status,
+    ...typeof billing.hourlyCredits === "number" ? { hourlyCredits: billing.hourlyCredits } : {},
+    ...typeof billing.nextChargeAt === "string" ? { nextChargeAt: billing.nextChargeAt } : {},
+    ...typeof billing.graceEndsAt === "string" ? { graceEndsAt: billing.graceEndsAt } : {}
+  };
+};
+var parseResourceStatus = (value) => {
+  const status = objectValue4(value);
+  if (status === null || typeof status.id !== "string" || typeof status.status !== "string") return null;
+  const billing = status.billing === void 0 ? void 0 : parseStatusBilling(status.billing);
+  if (status.billing !== void 0 && billing === null) return null;
+  return {
+    id: status.id,
+    status: status.status,
+    ...billing ? { billing } : {}
+  };
+};
+var parseResource = (value) => {
+  const resource = objectValue4(value);
+  if (resource === null || typeof resource.id !== "string" || typeof resource.kind !== "string" || !resourceKinds2.includes(resource.kind) || typeof resource.status !== "string" || resource.mode !== void 0 && (typeof resource.mode !== "string" || !resourceModes2.includes(resource.mode)) || resource.name !== void 0 && typeof resource.name !== "string" || resource.region !== void 0 && typeof resource.region !== "string" || resource.createdAt !== void 0 && typeof resource.createdAt !== "string") return null;
+  return {
+    id: resource.id,
+    kind: resource.kind,
+    status: resource.status,
+    ...typeof resource.mode === "string" ? { mode: resource.mode } : {},
+    ...typeof resource.name === "string" ? { name: resource.name } : {},
+    ...typeof resource.region === "string" ? { region: resource.region } : {},
+    ...typeof resource.createdAt === "string" ? { createdAt: resource.createdAt } : {}
+  };
+};
+var CloudResourcesClient = class {
+  #transport;
+  constructor(transport) {
+    this.#transport = transport;
+  }
+  async list(options) {
+    const response = await this.#transport.get(
+      "/v4/cloud/resources",
+      void 0,
+      options
+    );
+    const envelope = objectValue4(response);
+    const message = objectValue4(envelope?.message);
+    if (envelope?.success !== true || !Array.isArray(message?.resources)) {
+      throw new ErpcInvalidResponseError(
+        "ERPC returned an invalid Cloud resource list"
+      );
+    }
+    const resources = message.resources.map(parseResource);
+    if (resources.some((resource) => resource === null)) {
+      throw new ErpcInvalidResponseError(
+        "ERPC returned an invalid Cloud resource list"
+      );
+    }
+    return resources;
+  }
+  async get(resourceId, options) {
+    const normalizedId = resourceId.trim();
+    if (!normalizedId) {
+      throw new ErpcConfigError("resourceId must not be empty");
+    }
+    const response = await this.#transport.get(
+      `/v4/cloud/resources/${encodeURIComponent(normalizedId)}`,
+      void 0,
+      options
+    );
+    const envelope = objectValue4(response);
+    const message = objectValue4(envelope?.message);
+    const resource = envelope?.success === true ? parseResource(message?.resource) : null;
+    if (resource === null) {
+      throw new ErpcInvalidResponseError(
+        "ERPC returned an invalid Cloud resource"
+      );
+    }
+    return resource;
+  }
+  async getStatus(resourceId, options) {
+    const normalizedId = resourceId.trim();
+    if (!normalizedId) {
+      throw new ErpcConfigError("resourceId must not be empty");
+    }
+    const response = await this.#transport.get(
+      `/v4/cloud/resources/${encodeURIComponent(normalizedId)}/status`,
+      void 0,
+      options
+    );
+    const envelope = objectValue4(response);
+    const status = envelope?.success === true ? parseResourceStatus(envelope.message) : null;
+    if (status === null) {
+      throw new ErpcInvalidResponseError(
+        "ERPC returned an invalid Cloud resource status"
+      );
+    }
+    return status;
+  }
+};
+
+// src/cloud.ts
+var requireFetch2 = (provided) => {
+  const implementation = provided ?? globalThis.fetch;
+  if (typeof implementation !== "function") {
+    throw new ErpcConfigError(
+      "A Fetch API implementation is required in this runtime"
+    );
+  }
+  return implementation;
+};
+var cloudEndpoint = (value) => {
+  let endpoint;
+  try {
+    endpoint = new URL(value ?? DEFAULT_USER_ENDPOINT);
+  } catch {
+    throw new ErpcConfigError("endpoint must be an absolute HTTP(S) URL");
+  }
+  const isLocalHttp = endpoint.protocol === "http:" && ["127.0.0.1", "::1", "[::1]", "localhost"].includes(endpoint.hostname);
+  if (endpoint.protocol !== "https:" && !isLocalHttp) {
+    throw new ErpcConfigError("endpoint must use HTTPS except on localhost");
+  }
+  endpoint.search = "";
+  endpoint.hash = "";
+  endpoint.pathname = endpoint.pathname.replace(/\/+$/, "") || "/";
+  return endpoint;
+};
+var createErpcCloudClient = (config) => {
+  const accessToken = config.accessToken.trim();
+  if (!accessToken) {
+    throw new ErpcConfigError("accessToken must not be empty");
+  }
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new ErpcConfigError("timeoutMs must be a positive finite number");
+  }
+  const transport = new RestTransport({
+    apiKey: accessToken,
+    endpoint: cloudEndpoint(config.endpoint),
+    fetch: requireFetch2(config.fetch),
+    headers: config.headers ?? {},
+    timeoutMs
+  });
+  return {
+    catalog: new CloudCatalogClient(transport),
+    credit: new CloudCreditClient(transport),
+    resources: new CloudResourcesClient(transport),
+    usage: new UsageClient(transport)
+  };
+};
+
 exports.AccountClient = AccountClient;
+exports.CloudCatalogClient = CloudCatalogClient;
+exports.CloudCreditClient = CloudCreditClient;
+exports.CloudResourcesClient = CloudResourcesClient;
 exports.DEFAULT_ACCOUNT_ENDPOINT = DEFAULT_ACCOUNT_ENDPOINT;
 exports.DEFAULT_ENDPOINT = DEFAULT_ENDPOINT;
 exports.DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
+exports.DEFAULT_USER_ENDPOINT = DEFAULT_USER_ENDPOINT;
 exports.ETHEREUM_RPC_METHODS = ETHEREUM_RPC_METHODS;
 exports.ETHEREUM_SUBSCRIPTION_METHODS = ETHEREUM_SUBSCRIPTION_METHODS;
 exports.ErpcAbortedError = ErpcAbortedError;
@@ -1281,6 +1684,8 @@ exports.SOLANA_HISTORY_METHODS = SOLANA_HISTORY_METHODS;
 exports.SOLANA_LEADER_METHODS = SOLANA_LEADER_METHODS;
 exports.SOLANA_RPC_METHODS = SOLANA_RPC_METHODS;
 exports.SolanaSubscriptions = SolanaSubscriptions;
+exports.UsageClient = UsageClient;
 exports.createErpcClient = createErpcClient;
+exports.createErpcCloudClient = createErpcCloudClient;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map