Skip to main content

HTTP transport & response envelope

GStableHttp, DEFAULT_BASE_URL, DEFAULT_PUBLIC_BASE_URL, HttpMethod, GStableHttpOptions, and type ApiEnvelope are exported from gstable-js (src/http.ts, src/types/common.ts; see src/index.ts).

GStableHttp constructor​

Builds a low-level client that knows private and public base URLs and how to sign private requests. Prefer GStableClient unless you need AiPaymentResource or custom paths.

new GStableHttp(options)

Parameters​

Options object GStableHttpOptions (same fields as GStableClient uses):

FieldTypeRequiredDescription
apiKeystringYesTrimmed; prefixed with Bearer unless already present.
baseUrlstringNoPrivate API root; default DEFAULT_BASE_URL.
publicBaseUrlstringNoPublic API root; default DEFAULT_PUBLIC_BASE_URL.
fetchImpltypeof fetchNoOverride fetch (tests / custom runtimes).

Example​

import { GStableHttp } from 'gstable-js';

const http = new GStableHttp({
  apiKey: process.env.GSTABLE_API_KEY!,
});

requestJson​

Performs an authenticated GET or POST against the configured private base URL.

http.requestJson(method, path, body?)

Signature (conceptual)​

requestJson<T>(method: 'GET' | 'POST', path: string, body?: unknown): Promise<T>

Parameters​

NameTypeRequiredDescription
methodHttpMethod ('GET' | 'POST')YesOnly verbs used by the GStable API.
pathstringYesPath segment(s) relative to the private base URL; may include or omit a leading /.
bodyunknownNoFor POST, JSON-serialized when undefined is not passed; GET ignores body.

Headers (automatic)​

  • Accept: application/json
  • Content-Type: application/json
  • Authorization: Bearer + your API key

Returns​

Promise<T> — The API envelope’s data field after code === 0 and HTTP success.

Example​

import { GStableHttp } from 'gstable-js';

const http = new GStableHttp({ apiKey: process.env.GSTABLE_API_KEY! });
type MyDto = { ok: boolean };
const path: string = '...'; // advanced use only — prefer Resource methods
const data = await http.requestJson<MyDto>('GET', path);

requestPublicJson​

Performs GET or POST against the public base URL without Authorization.

http.requestPublicJson(method, path, body?)

Signature (conceptual)​

requestPublicJson<T>(method: 'GET' | 'POST', path: string, body?: unknown): Promise<T>

Parameters​

Same as requestJson for method, path, body.

Headers​

  • Accept, Content-Type only — no bearer token.

Returns​

Promise<T> — Unwrapped data on success.

Example​

Prefer client.capability.all() in application code instead of calling requestPublicJson directly.

Response handling​

The API responds with an envelope compatible with ApiEnvelope (generic data payload; see TypeScript in src/types/common.ts) with code, message, and data. The SDK:

  1. Reads response text and parses JSON.
  2. Validates a numeric code field exists.
  3. On HTTP error or invalid JSON / non-envelope → GStableError (often with hints for 401/403/non-JSON bodies).
  4. On code !== 0 → createTypedApiError → GStableProductError | GStableCommonError | GStablePlatformError | GStableError.
  5. On success → returns data only.

See the API introduction for the envelope shape.

Network errors​

Failures before any HTTP response use code: -1 and Network error: ….

Next​