@blueforge-studio/gas-client

Thin client for the gamevault (GAS) generation models as fronted by forge-gateway's /v1/gas/* route family.

• Credential: a forge-gateway token (gw_… static or gwm_… per-mission). This package never sees a gamevault API key — that lives in the gateway's tenant vault.
• Wire contracts: @blueforge-studio/vault7-api-schema (202 job envelope + job status).
• No retries: the typed errors say what is retryable; your caller owns retry policy.

Design + impl spec: docs/design/2026-10-20-federation-gamevault-model-gateway.md (gamevault-studio).

Install

The package lives on the private packr registry, so the registry has to be mapped per scope — not globally:

# ~/.npmrc (or the consumer's project .npmrc)
@blueforge-studio:registry=https://api.packr.blueforge.studio

pnpm add @blueforge-studio/gas-client zod

Do not set the default registry to packr (--registry=https://api.packr… or registry= in .npmrc): packr proxies unscoped upstream packages under a /name identity (zod → /zod), which npm rejects with EINVALIDPACKAGENAME. zod is a peer dependency of @blueforge-studio/vault7-api-schema, so it must resolve from npmjs.org.

Usage

import { createGasClient, createGasClientFromEnv } from '@blueforge-studio/gas-client';

// Explicit config — baseUrl is the gateway origin + /v1/gas prefix.
const client = createGasClient({
  baseUrl: 'https://gateway.blueforge.studio/v1/gas',
  apiKey: process.env.GAS_API_KEY!, // gw_/gwm_ token, never a provider key
});

// Or the null-when-unset convention (GAS_BASE_URL + GAS_API_KEY):
const maybe = createGasClientFromEnv();
if (!maybe) throw new Error('gamevault generation not configured');

const job = await client.generateAndWait('image', { prompt: 'a castle, solid black background' });
if (job.status === 'completed') {
  console.log(job.result?.files[0]?.url); // capability URL, fetchable without auth
}

// Split form, when you want to submit and poll separately:
const accepted = await client.generate('audio', { text: 'line' }, { action: 'narrate' });
const done = await client.waitForJob(accepted.jobId, { timeoutMs: 120_000 });

// Discovery + cost (both unvalidated passthrough of the gateway echo):
const catalogue = await client.models();
const pricing = await client.pricing(); // credit costs; 100 credits = $1

Errors

All extend GasApiError (status, code). Error bodies are read from both envelope shapes the platform emits ({error} / {message} / gateway {error:{code,message}}).

Development

pnpm --filter @blueforge-studio/gas-client run test        # vitest
pnpm --filter @blueforge-studio/gas-client run typecheck
pnpm --filter @blueforge-studio/gas-client run build