@vcityio/api-client

Typed TypeScript SDK for the vcity public API (/api/v1/*). Generated from the live OpenAPI spec via openapi-typescript + openapi-fetch, wrapped with ergonomic resource methods that read like an SDK instead of a raw HTTP client.

Install

npm install @vcityio/api-client
# or
pnpm add @vcityio/api-client
# or
bun add @vcityio/api-client

Requires Node 20+ (uses fetch + WHATWG URL).

Authentication

Two Bearer token types are accepted:

• vapi_… — long-lived org API keys generated from the vcity dashboard (Settings → API Keys). Use for integrations and server-to-server flows.
• vcli_… — short-lived user tokens issued via the CLI device flow. Inherit the user's org permissions.

Quick start

import { createVcityClient } from '@vcityio/api-client';

const sdk = createVcityClient({
  token: process.env.VCITY_API_KEY,
  // baseUrl defaults to https://vcity.io
});

// Discover the principal behind the token
const me = await sdk.me.get();

// List products (paginated)
const { data, total, hasMore } = await sdk.products.list('my-org-slug', {
  limit: 50,
  visibility: 'public',
});

// Single product
const product = await sdk.products.get('my-org-slug', data[0].id);

Resources

Every list endpoint returns a paginated envelope: { data, total, skip, limit, hasMore }. Methods throw ApiClientError on any non-2xx response — see Error handling.

| Resource | Methods | |----------|---------| | sdk.me | get() | | sdk.orgs | get(orgId) · listMembers(orgId, opts?) | | sdk.products | list(orgId, opts?) · get(orgId, productId) · create(orgId, body) · update(orgId, productId, body) · delete(orgId, productId) | | sdk.events | list(orgId, opts?) · get(orgId, eventId) · create(orgId, body) · update(orgId, eventId, body) · delete(orgId, eventId) | | sdk.rooms | list(orgId, opts?) · get(orgId, roomId) · create(orgId, body) · update(orgId, roomId, body) · delete(orgId, roomId) | | sdk.bookings | list(orgId, opts?) · get(orgId, bookingId) | | sdk.orders | list(orgId, opts?) · get(orgId, orderId) | | sdk.quotes | list(orgId, opts?) · get(orgId, quoteId) |

Write methods (create / update / delete) require a key with the matching *:write scope. Deletes are soft: the row stays in storage with a deletedAt timestamp and is filtered from subsequent reads.

orgId accepts the org's slug or its tokenized id.

Error handling

import { ApiClientError, createVcityClient } from '@vcityio/api-client';

try {
  const product = await sdk.products.get('acme', 'unknown');
} catch (e) {
  if (e instanceof ApiClientError) {
    console.error(e.status);   // 404
    console.error(e.body);     // { error: { code: 'not_found', message: '…' } }
    console.error(e.url);      // 'https://vcity.io/api/v1/orgs/acme/products/unknown'
  }
}

Escape hatch — raw openapi-fetch client

Need fine-grained control (headers per request, the { data, error, response } tuple pattern, multipart uploads)? Drop down to the raw client:

const { data, error, response } = await sdk.raw.GET('/api/v1/orgs/{orgId}/products', {
  params: { path: { orgId: 'acme' }, query: { limit: 5 } },
});

sdk.raw is a fully-typed openapi-fetch Client<paths>.

Configuration

createVcityClient({
  baseUrl: 'https://staging.vcity.io',     // default 'https://vcity.io'
  token: 'vapi_…',                          // attached as `Authorization: Bearer <token>`
  fetch: customFetch,                       // optional — useful for refresh wrappers or test stubs
  headers: { 'x-trace-id': '…' },           // merged into every request
});

When you provide a custom fetch, the SDK calls it with a Request and expects a Response back. The default Authorization header is still set unless your custom fetch overrides it.

Rate limits

Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. 429 responses include Retry-After. Quotas are tied to your org's vcity plan:

| Plan | Requests / day | |------|-----------------| | free | 1,000 | | starter | 50,000 | | pro | 500,000 | | enterprise | 5,000,000 |

A per-minute burst budget sits on top.

API reference

Full reference at https://vcity.io/docs/api — generated from the same OpenAPI spec this SDK is built from.

Support

Email [email protected] for SDK issues, feature requests, or API access problems.

Related

• @vcityio/cli — official vcity command-line tool built on top of this SDK.

License

MIT © Otherwise SAS