@zappyquote/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zappy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @zappyquote/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official JavaScript/TypeScript client for the Zappy API v1 - a thin wrapper over the documented HTTP API
+(https://zappyquote.com/developers/). The server stays authoritative for pricing, caps, idempotency and ownership;
+this package only carries requests and maps the public error envelope into typed errors.
+
+Version 0.1.0 · contract `openapi-1.0.0@9dff9fdfbcd8c1bd` · Node 18+ · zero dependencies · types included · MIT
+
+```bash
+# official download (always available):
+curl -O https://zappyquote.com/dl/zappy.mjs        # types: https://zappyquote.com/dl/zappy.d.ts
+# npm, ONLY once https://zappyquote.com/developers/ lists @zappyquote/sdk as published by Zappy:
+#   npm install @zappyquote/sdk
+```
+
+```js
+import { Zappy, ZappyError, newIdempotencyKey } from './zappy.mjs';   // or from '@zappyquote/sdk' when installed from npm
+
+const zappy = new Zappy();                                   // reads ZAPPY_API_KEY; or new Zappy({ apiKey })
+const { capabilities } = await zappy.capabilities();          // free
+const quote = await zappy.quote({ capability: 'zappy-image-pro' });   // free, reserves nothing
+
+// BILLABLE. maxCredits is a hard ceiling; the idempotency key makes a replay return the same job, never a second charge.
+const key = newIdempotencyKey('order-123');
+const r = await zappy.createImage({ prompt: 'a lighthouse at dusk', maxCredits: quote.credits_quoted, idempotencyKey: key });
+const job = r.status === 'succeeded' ? r : await zappy.waitForJob(r.job_id);   // 202 => poll (free)
+const asset = await zappy.getAsset(job.assets[0].asset_id);  // short-lived signed URL on Zappy's host
+```
+
+## Errors
+
+Every failure is a `ZappyError` subclass with `code` (the public error code), `status`, `requestId`, `rateLimit`
+(`{limit, remaining, reset}`) and `retryAfter`: `ZappyAuthError` (401 / `insufficient_scope` / not configured),
+`ZappyRateLimitError` (429), `ZappySpendError` (ceiling, cap, balance, idempotency), `ZappyNotFoundError`,
+`ZappyUnavailableError` (502/503, not available), `ZappyTransportError` (network, timeout, unreadable). Messages never
+contain a credential. Successful results carry `_meta` with the same metadata.
+
+## Webhooks
+
+```js
+import { verifyWebhookSignature } from './zappy.mjs';   // or '@zappyquote/sdk'
+// rawBody must be the exact bytes received; header is the Zappy-Signature value
+if (!verifyWebhookSignature(process.env.ZAPPY_WEBHOOK_SECRET, req.headers['zappy-signature'], rawBody)) return res.status(400).end();
+```
+
+## OAuth (PKCE)
+
+`pkcePair()` and `authorizeUrl({...})` build the authorization request for an OAuth app you registered in Zappy
+(Account -> Developer). Token exchange and consent happen on Zappy's authorization server; this package adds no
+second auth implementation. Pass `resource: 'https://zappyquote.com/mcp'` for a Remote MCP connection.
+
+## Paid calls are never retried
+
+`createImage` / `editImage` send one request. A retry is your decision - make it with the same `idempotencyKey`.

package/index.d.ts

@@ -0,0 +1,61 @@
+// Type definitions for @zappyquote/sdk 0.1.0 - thin client for the Zappy API v1 (contract openapi-1.0.0@9dff9fdfbcd8c1bd).
+export const SDK_VERSION: string;
+export const CONTRACT: string;
+export const DEFAULT_BASE_URL: string;
+
+export interface RateLimit { limit: number | null; remaining: number | null; reset: number | null; }
+export interface ResponseMeta { requestId: string | null; rateLimit: RateLimit | null; retryAfter: number | null; status?: number; }
+
+export type ErrorCode =
+  | 'balance_unavailable' | 'busy' | 'capability_retired' | 'daily_cap_reached' | 'delivery_unavailable'
+  | 'idempotency_conflict' | 'idempotency_key_required' | 'insufficient_credits' | 'insufficient_scope' | 'key_busy'
+  | 'key_misconfigured' | 'not_available' | 'pilot_closed' | 'rate_limited' | 'request_exceeds_key_ceiling'
+  | 'request_key_retired' | 'spend_check_unavailable' | 'unauthorized' | 'unsupported_duration' | 'unsupported_parameter'
+  | 'not_found' | 'unreachable' | 'bad_response' | 'not_configured' | 'wait_timeout' | string;
+
+export class ZappyError extends Error { code: ErrorCode; status: number; requestId: string | null; rateLimit: RateLimit | null; retryAfter: number | null; body: unknown;
+  /** Set on errors thrown by createImage/editImage: the key that was sent. Replay with it to recover a lost response safely. */
+  idempotencyKey?: string; }
+export class ZappyAuthError extends ZappyError {}
+export class ZappyRateLimitError extends ZappyError {}
+export class ZappySpendError extends ZappyError {}
+export class ZappyNotFoundError extends ZappyError {}
+export class ZappyUnavailableError extends ZappyError {}
+export class ZappyTransportError extends ZappyError {}
+
+export interface Capability { capability: string; credits: number; unit: string; operation: string; callable: boolean; async: boolean; }
+export interface CapabilitiesResponse { ok: true; capabilities: Capability[]; }
+export interface BalanceResponse { ok: true; balance: number; daily_free: number; }
+export interface UsageResponse { ok: true; usage: { key_prefix: string; credits_spent_today: number | null; daily_credits_cap: number | null; credits_remaining_today: number | null; max_credits_per_request: number | null; rate_limit_per_min: number | null; jobs_today: { succeeded: number | null; failed: number | null; processing: number | null } }; }
+export interface QuoteResponse { ok: true; capability: string; credits_quoted: number; }
+export interface AssetRef { asset_id: string; kind: string; }
+export interface JobResponse { ok: true; job_id: string; status: 'processing' | 'succeeded' | 'failed' | string; capability?: string; reason?: string; credits_quoted?: number; credits_charged?: number; credits_restored?: number; assets?: AssetRef[]; retry_after?: number; }
+export interface AssetResponse { ok: true; asset_id: string; kind: string; mime: string; bytes: number; sha256: string; url: string; expires_at: string; }
+export interface CreationsResponse { ok: true; items: JobResponse[]; next_cursor: string | null; }
+export type WithMeta<T> = T & { readonly _meta: ResponseMeta };
+
+export interface ZappyOptions { apiKey?: string; accessToken?: string; baseUrl?: string; clientName?: string; clientType?: 'sdk' | 'cli'; clientVersion?: string; timeoutMs?: number; fetch?: typeof fetch; }
+
+export class Zappy {
+  constructor(opts?: ZappyOptions);
+  baseUrl: string; clientName: string; clientType: string; clientVersion: string; timeoutMs: number; lastMeta: ResponseMeta | null;
+  capabilities(): Promise<WithMeta<CapabilitiesResponse>>;
+  balance(): Promise<WithMeta<BalanceResponse>>;
+  usage(): Promise<WithMeta<UsageResponse>>;
+  quote(p: { capability: string; duration?: number }): Promise<WithMeta<QuoteResponse>>;
+  getJob(jobId: string): Promise<WithMeta<JobResponse>>;
+  getAsset(assetId: string): Promise<WithMeta<AssetResponse>>;
+  listCreations(p?: { limit?: number; cursor?: string }): Promise<WithMeta<CreationsResponse>>;
+  waitForJob(jobId: string, p?: { intervalMs?: number; timeoutMs?: number; onPoll?: (j: JobResponse) => void }): Promise<WithMeta<JobResponse>>;
+  /** SPENDS CREDITS. Never retried automatically; replay with the same idempotencyKey returns the same job. */
+  createImage(p: { prompt: string; maxCredits: number; aspectRatio?: string; idempotencyKey?: string; onKey?: (key: string) => void }): Promise<WithMeta<JobResponse> & { idempotencyKey: string }>;
+  /** SPENDS CREDITS. `onKey` is called with the key BEFORE dispatch, so it can be persisted; the key is also on any error thrown. */
+  editImage(p: { sourceAssetId: string; prompt: string; maxCredits: number; aspectRatio?: string; idempotencyKey?: string; onKey?: (key: string) => void }): Promise<WithMeta<JobResponse> & { idempotencyKey: string }>;
+}
+export default Zappy;
+
+export function redact(s: string): string;
+export function newIdempotencyKey(prefix?: string): string;
+export function verifyWebhookSignature(secret: string, header: string, rawBody: string | Uint8Array, opts?: { now?: number; windowSeconds?: number }): boolean;
+export function pkcePair(): { verifier: string; challenge: string; method: 'S256' };
+export function authorizeUrl(p: { clientId: string; redirectUri: string; scope: string; state: string; challenge: string; resource?: string; issuer?: string }): string;

package/index.mjs

@@ -0,0 +1,204 @@
+/**
+ * @zappyquote/sdk - the official JavaScript/TypeScript client for the Zappy API v1.
+ *
+ * A THIN WRAPPER over the documented HTTP API (https://zappyquote.com/developers/). It holds no business rule:
+ * pricing, quotas, ceilings, idempotency and ownership are decided by the server, and this file only carries the
+ * request there and maps the public error envelope back into typed errors. Zero dependencies; Node >= 18 (fetch).
+ *
+ * Safety properties this client keeps:
+ *   - a credential is read from the constructor or ZAPPY_API_KEY, is never logged, and is redacted from every error;
+ *   - paid calls (createImage, editImage) are NEVER retried on their own: a retry of a paid call is the caller's
+ *     decision, made with the SAME idempotency key, so a replay can only ever return the same job;
+ *   - every mutating call sends an Idempotency-Key (yours, or one this client generates and returns to you);
+ *   - rate-limit metadata (RateLimit-*, Retry-After) and the X-Request-Id are exposed on every result and error.
+ */
+import { createHash, randomBytes, timingSafeEqual, createHmac } from 'node:crypto';
+
+export const SDK_VERSION = '0.1.0';
+/** sha256 prefix of the public_html/api/openapi.json this client was written against (see DEVELOPER_DISTRIBUTION.md). */
+export const CONTRACT = 'openapi-1.0.0@9dff9fdfbcd8c1bd';
+export const DEFAULT_BASE_URL = 'https://zappyquote.com/api/v1';
+
+const KEY_RE = /(zp_live_|zat_|zrt_|zcs_)[A-Za-z0-9_-]+/g;   // no leading boundary: an embedded credential is still a credential
+/** Replace any Zappy credential shape in a string with a redacted marker. Used on every error message and log line. */
+export function redact(s) { return String(s).replace(KEY_RE, (m, p) => p + '…redacted'); }
+
+/** A stable idempotency key for ONE intended operation. Keep it with the operation and reuse it to replay safely. */
+export function newIdempotencyKey(prefix = 'zq') {
+  const p = String(prefix).replace(/[^A-Za-z0-9._:-]/g, '').slice(0, 20) || 'zq';
+  return `${p}-${Date.now().toString(36)}-${randomBytes(9).toString('base64url')}`;
+}
+
+export class ZappyError extends Error {
+  constructor(message, { code = 'error', status = 0, requestId = null, rateLimit = null, retryAfter = null, body = null } = {}) {
+    super(redact(message));
+    this.name = 'ZappyError'; this.code = code; this.status = status; this.requestId = requestId;
+    this.rateLimit = rateLimit; this.retryAfter = retryAfter; this.body = body;
+  }
+}
+export class ZappyAuthError extends ZappyError { constructor(m, o) { super(m, o); this.name = 'ZappyAuthError'; } }
+export class ZappyRateLimitError extends ZappyError { constructor(m, o) { super(m, o); this.name = 'ZappyRateLimitError'; } }
+export class ZappySpendError extends ZappyError { constructor(m, o) { super(m, o); this.name = 'ZappySpendError'; } }
+export class ZappyNotFoundError extends ZappyError { constructor(m, o) { super(m, o); this.name = 'ZappyNotFoundError'; } }
+export class ZappyUnavailableError extends ZappyError { constructor(m, o) { super(m, o); this.name = 'ZappyUnavailableError'; } }
+export class ZappyTransportError extends ZappyError { constructor(m, o) { super(m, o); this.name = 'ZappyTransportError'; } }
+
+const SPEND_CODES = new Set(['insufficient_credits', 'daily_cap_reached', 'request_exceeds_key_ceiling', 'request_exceeds_ceiling', 'spend_check_unavailable', 'idempotency_key_required', 'idempotency_conflict']);
+function errorFor(status, body, meta) {
+  const code = body?.error?.code || (status === 429 ? 'rate_limited' : status === 401 ? 'unauthorized' : status === 404 ? 'not_found' : 'error');
+  const message = body?.error?.message || `Zappy API answered HTTP ${status}`;
+  const o = { code, status, ...meta, body };
+  if (status === 401 || code === 'unauthorized') return new ZappyAuthError(message, o);
+  if (status === 403 && code === 'insufficient_scope') return new ZappyAuthError(message, o);
+  if (status === 429 && code === 'rate_limited') return new ZappyRateLimitError(message, o);
+  if (SPEND_CODES.has(code)) return new ZappySpendError(message, o);
+  if (status === 404) return new ZappyNotFoundError(message, o);
+  if (status === 503 || status === 502 || code === 'not_available' || code === 'pilot_closed') return new ZappyUnavailableError(message, o);
+  return new ZappyError(message, o);
+}
+
+function readMeta(res) {
+  const h = res.headers;
+  const n = (k) => { const v = h.get(k); return v === null || v === '' || Number.isNaN(Number(v)) ? null : Number(v); };
+  const limit = n('ratelimit-limit'), remaining = n('ratelimit-remaining'), reset = n('ratelimit-reset');
+  return { requestId: h.get('x-request-id'), retryAfter: n('retry-after'),
+           rateLimit: limit === null && remaining === null ? null : { limit, remaining, reset } };
+}
+
+export class Zappy {
+  /**
+   * @param {{apiKey?: string, accessToken?: string, baseUrl?: string, clientName?: string, clientType?: string, timeoutMs?: number, fetch?: typeof fetch}} [opts]
+   */
+  constructor(opts = {}) {
+    const token = opts.accessToken || opts.apiKey || process.env.ZAPPY_API_KEY || '';
+    if (!token) throw new ZappyAuthError('No credential: pass { apiKey } or set ZAPPY_API_KEY. Create a key in Zappy under Account -> Developer.', { code: 'not_configured' });
+    Object.defineProperty(this, '_token', { value: token, enumerable: false, writable: false });
+    this.baseUrl = String(opts.baseUrl || process.env.ZAPPY_API_BASE || DEFAULT_BASE_URL).replace(/\/+$/, '');
+    this.clientType = opts.clientType === 'cli' ? 'cli' : 'sdk';
+    this.clientName = String(opts.clientName || 'zappy-sdk-js').toLowerCase().replace(/[^a-z0-9._-]/g, '').slice(0, 64) || 'zappy-sdk-js';
+    this.clientVersion = /^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$/.test(String(opts.clientVersion || '')) ? String(opts.clientVersion) : SDK_VERSION;
+    this.timeoutMs = Number(opts.timeoutMs || 60000);
+    this._fetch = opts.fetch || globalThis.fetch;
+    this.lastMeta = null;
+  }
+  /** Never reveals the credential - a redacted description only. */
+  toJSON() { return { baseUrl: this.baseUrl, clientName: this.clientName, credential: 'redacted' }; }
+  toString() { return `Zappy(${this.baseUrl})`; }
+
+  async _request(method, path, { body = null, idempotencyKey = null, query = null } = {}) {
+    let url = this.baseUrl + '/' + path.replace(/^\/+/, '');
+    if (query) { const q = new URLSearchParams(); for (const [k, v] of Object.entries(query)) if (v !== undefined && v !== null) q.set(k, String(v)); const s = q.toString(); if (s) url += '?' + s; }
+    const headers = { 'Authorization': 'Bearer ' + this._token, 'Accept': 'application/json',
+      'X-Zappy-Client-Type': this.clientType, 'X-Zappy-Client-Name': this.clientName, 'X-Zappy-Client-Version': this.clientVersion };
+    const init = { method, headers, redirect: 'manual' };
+    if (body !== null) { headers['Content-Type'] = 'application/json'; init.body = JSON.stringify(body); }
+    if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
+    // F5-003: the timeout covers the WHOLE exchange (connect, headers and body), and every transport failure is a ZappyTransportError
+    const ac = new AbortController(); const timer = setTimeout(() => ac.abort(), this.timeoutMs); init.signal = ac.signal;
+    let res, text, meta = null;
+    try {
+      res = await this._fetch(url, init);
+      meta = { ...readMeta(res), status: res.status }; this.lastMeta = meta;
+      // a redirect is never followed (redirect: 'manual'), so the credential can only ever reach the configured base URL
+      if (res.status >= 300 && res.status < 400) throw new ZappyTransportError('Zappy API answered with a redirect (HTTP ' + res.status + '), which this client never follows', { code: 'bad_response', status: res.status, ...meta });
+      text = await res.text();
+    } catch (e) {
+      if (e instanceof ZappyError) throw e;
+      throw new ZappyTransportError('Could not reach the Zappy API: ' + (e && e.name === 'AbortError' ? 'timeout' : (e && e.message) || 'network error'), { code: 'unreachable', ...(meta || {}) });
+    } finally { clearTimeout(timer); }
+    let json = null; try { json = JSON.parse(text); } catch { json = null; }
+    if (!res.ok || !json || json.ok === false) {
+      if (!json) throw new ZappyTransportError('Zappy returned an unreadable response (HTTP ' + res.status + ')', { code: 'bad_response', status: res.status, ...meta });
+      throw errorFor(res.status, json, meta);
+    }
+    return Object.defineProperty(json, '_meta', { value: { ...meta, status: res.status }, enumerable: false });
+  }
+
+  /** F5-BILL-001: a paid call's key is attached to EVERY outcome, including the error, so a lost response can be replayed safely. */
+  async _paid(path, body, key, onKey) {
+    if (onKey) onKey(key);
+    try { const r = await this._request('POST', path, { body, idempotencyKey: key }); r.idempotencyKey = key; return r; }
+    catch (e) { if (e && typeof e === 'object') e.idempotencyKey = key; throw e; }
+  }
+
+  /* ---- read (free) ---- */
+  capabilities() { return this._request('GET', 'capabilities'); }
+  balance() { return this._request('GET', 'balance'); }
+  usage() { return this._request('GET', 'usage'); }
+  quote({ capability, duration } = {}) { return this._request('POST', 'quote', { body: duration ? { capability, duration } : { capability } }); }
+  getJob(jobId) { return this._request('GET', 'jobs/' + encodeURIComponent(String(jobId))); }
+  getAsset(assetId) { return this._request('GET', 'assets/' + encodeURIComponent(String(assetId))); }
+  listCreations({ limit, cursor } = {}) { return this._request('GET', 'creations', { query: { limit, cursor } }); }
+
+  /**
+   * Poll a job until it is terminal (succeeded/failed) or `timeoutMs` elapses. Reads are free; polls respect the
+   * server's Retry-After when it sends one. Returns the final job record.
+   */
+  async waitForJob(jobId, { intervalMs = 3000, timeoutMs = 600000, onPoll = null } = {}) {
+    const start = Date.now();
+    for (;;) {
+      const j = await this.getJob(jobId);
+      if (onPoll) onPoll(j);
+      const st = String(j.status || j.job?.status || '');
+      if (st === 'succeeded' || st === 'failed') return j;
+      if (Date.now() - start > timeoutMs) throw new ZappyError('Timed out waiting for job ' + jobId + ' (it is still ' + (st || 'processing') + '; keep polling getJob)', { code: 'wait_timeout' });
+      const ra = j._meta?.retryAfter; await new Promise(r => setTimeout(r, ra ? ra * 1000 : intervalMs));
+    }
+  }
+
+  /* ---- write (SPENDS CREDITS; never auto-retried) ---- */
+  /**
+   * @param {{prompt: string, maxCredits: number, aspectRatio?: string, idempotencyKey?: string}} p
+   * @returns {Promise<object & {idempotencyKey: string}>} the API response (200 finished or 202 processing) plus the key used
+   */
+  async createImage({ prompt, maxCredits, aspectRatio, idempotencyKey, onKey } = {}) {
+    if (!prompt) throw new ZappyError('prompt is required', { code: 'prompt_required' });
+    if (!(Number(maxCredits) > 0)) throw new ZappyError('maxCredits is required: a paid call needs a hard credit ceiling', { code: 'max_credits_required' });
+    const key = idempotencyKey || newIdempotencyKey('img');
+    const body = { prompt, max_credits: Number(maxCredits) }; if (aspectRatio) body.aspect_ratio = aspectRatio;
+    return this._paid('images', body, key, onKey);
+  }
+  async editImage({ sourceAssetId, prompt, maxCredits, aspectRatio, idempotencyKey, onKey } = {}) {
+    if (!sourceAssetId || !prompt) throw new ZappyError('sourceAssetId and prompt are required', { code: 'source_required' });
+    if (!(Number(maxCredits) > 0)) throw new ZappyError('maxCredits is required: a paid call needs a hard credit ceiling', { code: 'max_credits_required' });
+    const key = idempotencyKey || newIdempotencyKey('edit');
+    const body = { source_asset_id: sourceAssetId, prompt, max_credits: Number(maxCredits) }; if (aspectRatio) body.aspect_ratio = aspectRatio;
+    return this._paid('images/edit', body, key, onKey);
+  }
+}
+
+/* ---- webhooks (zq.webhook.v1) ---- */
+/**
+ * Verify a Zappy webhook delivery. `header` is the Zappy-Signature value (t=..,v1=..), `rawBody` the exact bytes received.
+ * Returns true only for an authentic delivery inside the replay window (default 300 s). Compares in constant time.
+ */
+export function verifyWebhookSignature(secret, header, rawBody, { now = Math.floor(Date.now() / 1000), windowSeconds = 300 } = {}) {
+  if (typeof secret !== 'string' || !secret || typeof header !== 'string') return false;
+  let t = null; const sigs = [];
+  for (const part of header.split(',')) {
+    const i = part.indexOf('='); if (i < 0) continue;
+    const k = part.slice(0, i).trim(), v = part.slice(i + 1).trim();
+    if (k === 't' && /^[0-9]+$/.test(v)) t = Number(v);
+    if (k === 'v1' && /^[a-f0-9]{64}$/.test(v)) sigs.push(v);
+  }
+  if (t === null || !sigs.length || Math.abs(now - t) > windowSeconds) return false;
+  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody), 'utf8');
+  const want = createHmac('sha256', secret).update(t + '.').update(body).digest('hex');
+  const w = Buffer.from(want, 'hex');
+  return sigs.some(s => { const b = Buffer.from(s, 'hex'); return b.length === w.length && timingSafeEqual(b, w); });
+}
+
+/* ---- OAuth 2.1 PKCE helpers (pure functions; the authorization server stays the ONE auth implementation) ---- */
+export function pkcePair() {
+  const verifier = randomBytes(48).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+  return { verifier, challenge, method: 'S256' };
+}
+/** Build the /oauth/authorize URL for an owner-registered Zappy OAuth app. `resource` is the API by default; pass
+ *  'https://zappyquote.com/mcp' for a Remote MCP connection (the app must have been registered as MCP-capable). */
+export function authorizeUrl({ clientId, redirectUri, scope, state, challenge, resource = 'https://zappyquote.com/api/v1', issuer = 'https://zappyquote.com' }) {
+  const q = new URLSearchParams({ client_id: clientId, redirect_uri: redirectUri, response_type: 'code', scope, state, code_challenge: challenge, code_challenge_method: 'S256', resource });
+  return issuer.replace(/\/+$/, '') + '/oauth/authorize?' + q.toString();
+}
+
+export default Zappy;

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@zappyquote/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Official Zappy API client for JavaScript/TypeScript - a thin wrapper over the documented Zappy API v1.",
+  "keywords": ["zappy", "ai", "image-generation", "api", "sdk"],
+  "homepage": "https://zappyquote.com/developers/",
+  "bugs": { "url": "https://zappyquote.com/contact.html" },
+  "license": "MIT",
+  "author": "Zappy",
+  "type": "module",
+  "main": "index.mjs",
+  "types": "index.d.ts",
+  "exports": { ".": { "types": "./index.d.ts", "import": "./index.mjs" } },
+  "files": ["index.mjs", "index.d.ts", "README.md", "LICENSE"],
+  "engines": { "node": ">=18.0.0" },
+  "repository": { "type": "git", "url": "https://zappyquote.com/developers/" },
+  "publishConfig": { "access": "public" },
+  "dependencies": {},
+  "scripts": {
+    "test": "node test.mjs"
+  }
+}