Skip to content

SDK Overview

The Simple Feature Requests SDK is a TypeScript/JavaScript client library for the Simple Feature Requests GraphQL API. It provides a typed, promise-based interface for all API operations and can be used in Node.js (v18+) or in the browser.

Features

  • Typed API: All operations and entities are fully typed (TypeScript). Use with or without TypeScript in your project.
  • Authentication: Optional Bearer token (or async token getter) for authenticated requests. Public operations work without a token.
  • Error handling: Consistent SdkError with code and message; maps API HTTP and GraphQL errors to a single error type.
  • Dual format: Published as ESM and CommonJS; works with modern bundlers and Node.
  • No React dependency: Uses fetch only; suitable for scripts, servers, and any JS environment with fetch.

Browser vs Node

  • Browser: Use the SDK in React, Vue, or vanilla JS. Provide getAccessToken (e.g. from Clerk's getToken()) for authenticated calls.
  • Node.js: Requires Node 18+ (for native fetch) or provide a custom fetch in the client config (e.g. node-fetch).

Authentication model

The API uses Clerk for identity. The SDK does not handle sign-in; it only sends the token you provide:

  • Unauthenticated: Omit getAccessToken. Only public operations (e.g. hello, public project reads) will succeed.
  • Authenticated: Pass getAccessToken: () => getToken() (or async) so the SDK sends Authorization: Bearer <token> on each request. The API resolves the token to the current user.

See Quick Start for a minimal example and API Authentication for full details.