@tanqory/plugin-sdk 0.2.0

package/README.md

@@ -0,0 +1,117 @@
+# @tanqory/plugin-sdk
+
+Build an app for the Tanqory marketplace. You host it; Tanqory frames it, routes
+its API calls, and tells it who the merchant is.
+
+```bash
+npm install @tanqory/plugin-sdk
+```
+
+## The two halves
+
+```ts
+import { createTanqoryApp, verifyWebhookSignature } from '@tanqory/plugin-sdk' // your server
+import { useTanqoryApp } from '@tanqory/plugin-sdk/client' // your UI
+```
+
+Separate entry points on purpose: importing the server half must not drag React
+into a serverless function.
+
+## Embedded UI
+
+```tsx
+'use client'
+import { useTanqoryApp } from '@tanqory/plugin-sdk/client'
+
+export default function Page() {
+  const { ready, store, api } = useTanqoryApp()
+  if (!ready) return <p>Loading…</p>
+
+  return (
+    <button onClick={() => api!.get('/orders', { limit: 5 }).then(console.log)}>
+      Recent orders for {store!.storeName}
+    </button>
+  )
+}
+```
+
+`useTanqoryApp` performs the whole handshake: verifying who framed you,
+requesting store context, retrying an unanswered handshake, holding a token in
+memory and renewing it before it expires, and reporting a dead session to the
+host. Getting any of that wrong produces a blank frame with a clean console,
+which is unpleasant to debug from the outside.
+
+## Server side
+
+```ts
+const tanqory = createTanqoryApp({
+  clientId: process.env.TANQORY_CLIENT_ID!,
+  clientSecret: process.env.TANQORY_CLIENT_SECRET!,
+})
+
+const orders = await tanqory.store(storeId).get('/orders', { query: { limit: 5 } })
+```
+
+Tokens are cached per store and renewals are single-flighted, so parallel work
+triggers one exchange rather than one each.
+
+## Webhooks
+
+```ts
+export async function POST(request: Request) {
+  const raw = await request.text()
+  if (!verifyWebhookSignature(raw, request.headers.get('x-tanqory-signature'), SECRET)) {
+    return new Response('bad signature', { status: 401 })
+  }
+  …
+}
+```
+
+Pass the **raw** body. Re-serialising a parsed object changes key order and
+whitespace, and the signature will not match.
+
+## Three things that will save you a day
+
+**Never name an API host.** Every request is relative and Tanqory's edge resolves
+which regional cell holds the store from the id in the path. An app that
+hardcodes a hostname is pinned to one cell and breaks for merchants elsewhere.
+
+**Never send `X-Frame-Options`.** It has no allow-list form, so `SAMEORIGIN`
+overrides your `Content-Security-Policy: frame-ancestors` in browsers that still
+read it, and the dashboard renders a blank frame. Set `frame-ancestors` instead.
+
+**Never navigate to a login page.** You are inside an iframe: a login screen
+renders in a box, and if it escaped it would throw the merchant out of their
+dashboard. On auth failure the SDK tells the host and the host decides.
+
+## The manifest
+
+`tanqory.app.json` is what review approves, and the only thing a version pins.
+Your code is yours — deploy whenever you like. Changing the _manifest_ (a new
+scope, origin, or webhook topic) needs approval, because it changes what
+merchants agreed to.
+
+```json
+{
+  "handle": "order-notifier",
+  "name": "Order Notifier",
+  "appUrl": "https://order-notifier.example.com",
+  "devUrl": "http://localhost:3000",
+  "embedded": { "enabled": true, "path": "/embed" },
+  "scopes": ["orders.view"],
+  "webhooks": [{ "topic": "orders/create", "path": "/hooks/orders" }]
+}
+```
+
+`devUrl` is used **instead of** `appUrl`, and only on a DEVELOPMENT store — so
+you can point at localhost while building without any localhost origin ever
+being trusted for a real merchant.
+
+Validate it in your own build:
+
+```ts
+import { parseAppManifest } from '@tanqory/plugin-sdk'
+parseAppManifest(JSON.parse(readFileSync('tanqory.app.json', 'utf8')))
+```
+
+It reports every problem at once rather than stopping at the first.

package/dist/auth.d.ts

@@ -0,0 +1,38 @@
+export interface TanqoryAppCredentials {
+    clientId: string;
+    clientSecret: string;
+    /** Defaults to `TANQORY_API_BASE`, then production. */
+    apiBase?: string;
+}
+/**
+ * Exchanges your app credentials for a token scoped to one store.
+ *
+ * One instance per app; it caches per store and single-flights renewals, so N
+ * concurrent calls trigger at most one exchange rather than N. That matters
+ * because the token endpoint is rate limited, and a burst of parallel work is
+ * exactly when an app would otherwise hammer it.
+ *
+ * There is no refresh token by design. Renewal re-runs the exchange, which
+ * re-checks that the merchant still has your app installed — so uninstalling
+ * stops your access within one token lifetime rather than whenever a refresh
+ * token happened to expire.
+ */
+export declare class TanqoryAuth {
+    private readonly credentials;
+    private readonly apiBase;
+    private readonly cache;
+    private readonly inFlight;
+    constructor(credentials: TanqoryAppCredentials);
+    /** A token good right now for this store, renewing only when it has to. */
+    tokenFor(storeId: string): Promise<string>;
+    /** What the merchant actually granted. Useful for hiding UI you cannot serve. */
+    scopesFor(storeId: string): Promise<string[]>;
+    /**
+     * Drop a cached token — call after a 401 so the next request re-exchanges.
+     * Cheaper than pre-emptively shortening every lifetime.
+     */
+    invalidate(storeId: string): void;
+    private entryFor;
+    private exchange;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAkBD;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAW;IAKV,OAAO,CAAC,QAAQ,CAAC,WAAW;IAJxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;gBAEtC,WAAW,EAAE,qBAAqB;IAQ/D,2EAA2E;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIhD,iFAAiF;IAC3E,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAInD;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;YAInB,QAAQ;YAYR,QAAQ;CAsCvB"}

package/dist/auth.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TanqoryAuth = void 0;
+const errors_1 = require("./errors");
+/** Where the platform lives. Overridable only for Tanqory's own dev tier. */
+const DEFAULT_API_BASE = 'https://api.tanqory.com';
+/**
+ * Renew this long before the token actually expires.
+ *
+ * A token that expires mid-flight produces a 401 the app cannot distinguish
+ * from a revoked installation, so it is worth spending a little lifetime to
+ * never see one.
+ */
+const EXPIRY_SKEW_MS = 30_000;
+/**
+ * Exchanges your app credentials for a token scoped to one store.
+ *
+ * One instance per app; it caches per store and single-flights renewals, so N
+ * concurrent calls trigger at most one exchange rather than N. That matters
+ * because the token endpoint is rate limited, and a burst of parallel work is
+ * exactly when an app would otherwise hammer it.
+ *
+ * There is no refresh token by design. Renewal re-runs the exchange, which
+ * re-checks that the merchant still has your app installed — so uninstalling
+ * stops your access within one token lifetime rather than whenever a refresh
+ * token happened to expire.
+ */
+class TanqoryAuth {
+    credentials;
+    apiBase;
+    cache = new Map();
+    inFlight = new Map();
+    constructor(credentials) {
+        this.credentials = credentials;
+        this.apiBase = (credentials.apiBase ??
+            process.env.TANQORY_API_BASE ??
+            DEFAULT_API_BASE).replace(/\/+$/, '');
+    }
+    /** A token good right now for this store, renewing only when it has to. */
+    async tokenFor(storeId) {
+        return (await this.entryFor(storeId)).token;
+    }
+    /** What the merchant actually granted. Useful for hiding UI you cannot serve. */
+    async scopesFor(storeId) {
+        return (await this.entryFor(storeId)).scopes;
+    }
+    /**
+     * Drop a cached token — call after a 401 so the next request re-exchanges.
+     * Cheaper than pre-emptively shortening every lifetime.
+     */
+    invalidate(storeId) {
+        this.cache.delete(storeId);
+    }
+    async entryFor(storeId) {
+        const cached = this.cache.get(storeId);
+        if (cached && Date.now() < cached.usableUntil)
+            return cached;
+        const pending = this.inFlight.get(storeId);
+        if (pending)
+            return pending;
+        const exchange = this.exchange(storeId).finally(() => this.inFlight.delete(storeId));
+        this.inFlight.set(storeId, exchange);
+        return exchange;
+    }
+    async exchange(storeId) {
+        const response = await fetch(`${this.apiBase}/api/v1/apps/token`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', accept: 'application/json' },
+            body: JSON.stringify({
+                grant_type: 'client_credentials',
+                client_id: this.credentials.clientId,
+                client_secret: this.credentials.clientSecret,
+                store_id: storeId,
+            }),
+        });
+        if (response.status === 401)
+            throw new errors_1.TanqoryAuthError();
+        if (!response.ok) {
+            throw new errors_1.TanqoryError(`Token exchange failed with ${response.status}.`, response.status, 'TOKEN_EXCHANGE');
+        }
+        const body = (await response.json());
+        if (!body.access_token) {
+            throw new errors_1.TanqoryError('Token exchange returned no access_token.', 500, 'TOKEN_EXCHANGE');
+        }
+        const entry = {
+            token: body.access_token,
+            usableUntil: Date.now() + Math.max((body.expires_in ?? 600) * 1000 - EXPIRY_SKEW_MS, 0),
+            scopes: body.scope ? body.scope.split(' ').filter(Boolean) : [],
+        };
+        this.cache.set(storeId, entry);
+        return entry;
+    }
+}
+exports.TanqoryAuth = TanqoryAuth;
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/client/index.d.ts

@@ -0,0 +1,67 @@
+import { type BridgeContext } from '@tanqory/app-bridge';
+/**
+ * The embedded half of the SDK.
+ *
+ * Everything here runs in the browser, inside the iframe the Tanqory dashboard
+ * renders your app in. Kept in its own entry point so importing the server half
+ * cannot drag React into a serverless function.
+ */
+export type TanqoryAppStatus = 'loading' | 'ready' | 'error';
+export interface TanqoryAppState {
+    status: TanqoryAppStatus;
+    ready: boolean;
+    error: string | null;
+    /** Non-null once `ready`. */
+    store: BridgeContext | null;
+    /** Call the API as the merchant currently looking at your app. */
+    api: EmbeddedApi | null;
+    /** True when the merchant granted this scope. Fails closed while loading. */
+    can: (scope: string) => boolean;
+    /** Show the dashboard's own toast — one rendered inside a sized iframe is clipped. */
+    toast: (variant: 'success' | 'error' | 'info', title: string, description?: string) => void;
+}
+export interface EmbeddedApi {
+    get<T = unknown>(path: string, query?: Record<string, string | number | boolean>): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    delete<T = unknown>(path: string): Promise<T>;
+}
+export interface UseTanqoryAppOptions {
+    /**
+     * Origins permitted to embed you. Defaults to Tanqory's dashboard.
+     *
+     * The bridge refuses to post to, or accept from, anything not on this list,
+     * and never uses `'*'` — so a page that frames your app without permission
+     * receives no context, no token, and no store data.
+     */
+    allowedHostOrigins?: string[];
+}
+/**
+ * Boot an embedded Tanqory app.
+ *
+ * ```tsx
+ * const { ready, store, api } = useTanqoryApp()
+ * if (!ready) return <p>Loading…</p>
+ * return <p>Hello {store.storeName}</p>
+ * ```
+ *
+ * This replaces the handshake every embedded app would otherwise reimplement:
+ * creating the bridge guest, verifying who framed you, requesting context,
+ * retrying an unanswered handshake, holding a token in memory and renewing it
+ * before it expires, and telling the host when the session dies. Getting any of
+ * those wrong produces a blank frame with a clean console, which is a genuinely
+ * hard thing to debug from the outside.
+ *
+ * ## Two rules the platform enforces, which this respects for you
+ *
+ * **Never navigate to a login page.** Inside an iframe that renders a login
+ * screen in a box, and if it escaped it would throw the merchant out of their
+ * dashboard. On auth failure the host is told and decides.
+ *
+ * **Never name an API host.** Requests are relative; Tanqory's edge resolves
+ * which regional cell holds this store from the store id in the path. An app
+ * that hardcodes a host is pinned to one cell and breaks for merchants
+ * elsewhere.
+ */
+export declare function useTanqoryApp(options?: UseTanqoryAppOptions): TanqoryAppState;
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,aAAa,EAAoB,MAAM,qBAAqB,CAAA;AAG7F;;;;;;GAMG;AAEH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;AAE5D,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,gBAAgB,CAAA;IACxB,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,6BAA6B;IAC7B,KAAK,EAAE,aAAa,GAAG,IAAI,CAAA;IAC3B,kEAAkE;IAClE,GAAG,EAAE,WAAW,GAAG,IAAI,CAAA;IACvB,6EAA6E;IAC7E,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAA;IAC/B,sFAAsF;IACtF,KAAK,EAAE,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5F;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAC7F,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAC3D,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAC5D,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CAC9C;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAA;CAC9B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,eAAe,CA4EjF"}

package/dist/client/index.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTanqoryApp = useTanqoryApp;
+const app_bridge_1 = require("@tanqory/app-bridge");
+const react_1 = require("react");
+const DEFAULT_HOST_ORIGINS = ['https://app.tanqory.com'];
+/**
+ * Boot an embedded Tanqory app.
+ *
+ * ```tsx
+ * const { ready, store, api } = useTanqoryApp()
+ * if (!ready) return <p>Loading…</p>
+ * return <p>Hello {store.storeName}</p>
+ * ```
+ *
+ * This replaces the handshake every embedded app would otherwise reimplement:
+ * creating the bridge guest, verifying who framed you, requesting context,
+ * retrying an unanswered handshake, holding a token in memory and renewing it
+ * before it expires, and telling the host when the session dies. Getting any of
+ * those wrong produces a blank frame with a clean console, which is a genuinely
+ * hard thing to debug from the outside.
+ *
+ * ## Two rules the platform enforces, which this respects for you
+ *
+ * **Never navigate to a login page.** Inside an iframe that renders a login
+ * screen in a box, and if it escaped it would throw the merchant out of their
+ * dashboard. On auth failure the host is told and decides.
+ *
+ * **Never name an API host.** Requests are relative; Tanqory's edge resolves
+ * which regional cell holds this store from the store id in the path. An app
+ * that hardcodes a host is pinned to one cell and breaks for merchants
+ * elsewhere.
+ */
+function useTanqoryApp(options = {}) {
+    const [status, setStatus] = (0, react_1.useState)('loading');
+    const [error, setError] = (0, react_1.useState)(null);
+    const [store, setStore] = (0, react_1.useState)(null);
+    const bridgeRef = (0, react_1.useRef)(null);
+    const tokenRef = (0, react_1.useRef)(null);
+    const booted = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        // React Strict Mode double-invokes effects in development. The handshake is
+        // not idempotent from the host's side, so guard it.
+        if (booted.current)
+            return;
+        booted.current = true;
+        const bridge = (0, app_bridge_1.createBridgeGuest)({
+            allowedOrigins: options.allowedHostOrigins ?? DEFAULT_HOST_ORIGINS,
+        });
+        bridgeRef.current = bridge;
+        if (!bridge.isEmbedded || !bridge.hostOrigin) {
+            setError('This app must be opened from the Tanqory dashboard.');
+            setStatus('error');
+            return;
+        }
+        const stop = bridge.start();
+        let cancelled = false;
+        void (async () => {
+            try {
+                // Retried, because a single unanswered handshake is unrecoverable and
+                // looks exactly like a hung app: the frame stays blank, the console is
+                // clean, and every network request is green.
+                let context = null;
+                for (let attempt = 1; attempt <= 3 && !context; attempt += 1) {
+                    try {
+                        context = await bridge.init();
+                    }
+                    catch (initError) {
+                        if (cancelled)
+                            return;
+                        if (attempt === 3)
+                            throw initError;
+                    }
+                }
+                if (cancelled || !context)
+                    return;
+                setStore(context);
+                setStatus('ready');
+                bridge.ready();
+            }
+            catch (bootError) {
+                if (cancelled)
+                    return;
+                setError(bootError instanceof Error ? bootError.message : 'Failed to start.');
+                setStatus('error');
+            }
+        })();
+        return () => {
+            cancelled = true;
+            stop();
+        };
+    }, [options.allowedHostOrigins]);
+    const api = store ? buildApi(bridgeRef, tokenRef, store.storeId) : null;
+    return {
+        status,
+        ready: status === 'ready',
+        error,
+        store,
+        api,
+        can: (scope) => 
+        // `'*'` is the store-owner wildcard. Without this branch the one merchant
+        // guaranteed to be allowed everything would see no actions at all.
+        store?.permissions.includes('*') || store?.permissions.includes(scope) || false,
+        toast: (variant, title, description) => bridgeRef.current?.post('TOAST', { variant, title, description }),
+    };
+}
+/** Renew this long before expiry — a token that dies mid-flight becomes a 401. */
+const EXPIRY_SKEW_MS = 30_000;
+function buildApi(bridgeRef, tokenRef, storeId) {
+    async function token() {
+        const cached = tokenRef.current;
+        if (cached && Date.now() < cached.expiresAt - EXPIRY_SKEW_MS)
+            return cached.value;
+        const bridge = bridgeRef.current;
+        if (!bridge)
+            throw new Error('Bridge is not ready.');
+        // The host holds a live token and answers instantly. It is also the only
+        // party that can recover a dead session, which is why failure is reported
+        // to it rather than handled here.
+        const { token: value, expiresAt } = await bridge.requestToken();
+        tokenRef.current = { value, expiresAt };
+        return value;
+    }
+    async function request(method, path, body, query) {
+        // Relative on purpose — see the note on `useTanqoryApp`.
+        const url = new URL(`/api/v1/stores/${storeId}${path.startsWith('/') ? path : `/${path}`}`, window.location.origin);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            url.searchParams.set(key, String(value));
+        }
+        const response = await fetch(url, {
+            method,
+            headers: {
+                authorization: `Bearer ${await token()}`,
+                accept: 'application/json',
+                ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (response.status === 401) {
+            tokenRef.current = null;
+            bridgeRef.current?.post('AUTH_EXPIRED', undefined);
+            throw new Error('The session expired.');
+        }
+        if (!response.ok)
+            throw new Error(`Request failed with ${response.status}.`);
+        if (response.status === 204)
+            return undefined;
+        return (await response.json());
+    }
+    return {
+        get: (path, query) => request('GET', path, undefined, query),
+        post: (path, body) => request('POST', path, body),
+        patch: (path, body) => request('PATCH', path, body),
+        delete: (path) => request('DELETE', path),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,53 @@
+import { TanqoryAuth, type TanqoryAppCredentials } from './auth';
+export interface RequestOptions {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/**
+ * A REST client for one store.
+ *
+ * Paths are relative to that store: `get('/orders')` reaches
+ * `/api/v1/stores/<storeId>/orders`. You never assemble a store path yourself,
+ * which is the point — a hand-built path is how an app ends up reading a store
+ * it was not installed on and getting a confusing 403 instead of a clear one.
+ *
+ * There is no `baseURL` option, and no way to name a host. Tanqory runs one
+ * store's data in one of several regional cells, and which cell is not
+ * something an app should know, cache, or get wrong: the platform edge resolves
+ * it per request from the store id already in the path.
+ */
+export declare class TanqoryStoreClient {
+    private readonly auth;
+    private readonly storeId;
+    private readonly apiBase;
+    constructor(auth: TanqoryAuth, storeId: string, apiBase: string);
+    get<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    /** What the merchant granted this app on this store. */
+    scopes(): Promise<string[]>;
+    private request;
+    private messageFrom;
+}
+/**
+ * Entry point for server-side work.
+ *
+ * ```ts
+ * const tanqory = createTanqoryApp({
+ *   clientId: process.env.TANQORY_CLIENT_ID!,
+ *   clientSecret: process.env.TANQORY_CLIENT_SECRET!,
+ * })
+ *
+ * const orders = await tanqory.store(storeId).get('/orders', { query: { limit: 5 } })
+ * ```
+ */
+export declare function createTanqoryApp(credentials: TanqoryAppCredentials): {
+    /** A client bound to one store. Memoised, so calling it in a loop is free. */
+    store(storeId: string): TanqoryStoreClient;
+    auth: TanqoryAuth;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,qBAAqB,EAAE,MAAM,QAAQ,CAAA;AAGhE,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAA;IAC7D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAFP,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM;IAGlC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAIpE,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrF,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAIpF,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAItF,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAIvE,wDAAwD;IACxD,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YAIb,OAAO;YAmDP,WAAW;CAQ1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,qBAAqB;IAW/D,8EAA8E;mBAC/D,MAAM,GAAG,kBAAkB;;EAU7C"}