@querais/sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QueraIS contributors
+
+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

@@ -0,0 +1,108 @@
+# @querais/sdk
+
+TypeScript client + CLI for [QueraIS](https://github.com/ShavitR/querais) — a
+decentralized AI inference marketplace where independent GPU nodes serve your
+requests and settle on-chain.
+
+> **Testnet only — no real value.** By using the network you accept the
+> [Terms](https://github.com/ShavitR/querais/blob/main/docs/TERMS.md); read the
+> [Privacy Notice](https://github.com/ShavitR/querais/blob/main/docs/PRIVACY.md)
+> first (~5% of prompts are re-run for verification; prompts execute on
+> independent operators' machines).
+
+## Install
+
+```bash
+npm install @querais/sdk
+```
+
+## Quickstart
+
+```ts
+import { QueraisClient } from '@querais/sdk';
+
+const client = new QueraisClient({
+  baseUrl: 'https://querais-gateway.fly.dev',
+  apiKey: 'sk-querais-…', // issued by the gateway operator
+});
+
+// Buffered
+const r = await client.chat([{ role: 'user', content: 'Explain Arbitrum in one sentence.' }], {
+  model: 'gemma3:4b',
+});
+console.log(r.content, r.usage);
+
+// Streaming
+for await (const delta of client.chatStream([{ role: 'user', content: 'Hi' }], {
+  model: 'gemma3:4b',
+})) {
+  process.stdout.write(delta);
+}
+```
+
+### Already using the `openai` package?
+
+The gateway is OpenAI-compatible — you don't need this SDK at all:
+
+```ts
+import OpenAI from 'openai';
+const client = new OpenAI({ baseURL: 'https://querais-gateway.fly.dev/v1', apiKey: 'sk-…' });
+```
+
+This SDK adds the QueraIS-specific surface on top: marketplace routing options
+(`maxPricePer1kTokens`, `minReputation`), node/stats introspection, and
+batched-settlement sessions.
+
+## Marketplace helpers
+
+```ts
+await client.models(); // model ids available on the network
+await client.nodes(); // active nodes: wallet, reputation, models, prices
+await client.stats(); // network totals
+```
+
+## Batched settlement (pay once, run thousands of jobs)
+
+Deposit $QAIS into the CreditAccount contract once, sign **one** EIP-712
+spending cap off-chain (zero gas), then fire unlimited jobs — the gateway
+settles them in batches. The cap bounds the most it can ever spend.
+
+```ts
+const client = new QueraisClient({
+  baseUrl: 'https://querais-gateway.fly.dev',
+  apiKey: 'sk-…',
+  privateKey: '0x…', // requester wallet — used ONCE, off-chain, to sign the cap
+});
+
+await client.openSession({
+  maxSpendWei: 10n ** 21n, // 1000 QAIS ceiling for this session
+  nonce: 1n,
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+});
+
+await client.chat([{ role: 'user', content: 'Hi' }], { model: 'gemma3:4b' });
+await client.sessionStatus(); // cap, spend, credit balance, headroom
+```
+
+## CLI
+
+The package ships a `querais` binary:
+
+```bash
+export QUERAIS_BASE_URL=https://querais-gateway.fly.dev
+export QUERAIS_API_KEY=sk-…
+export QUERAIS_MODEL=gemma3:4b
+
+querais chat "Hello"   # streams a completion
+querais models         # models available on the network
+querais nodes          # active nodes + reputation
+querais stats          # network stats
+```
+
+## Requirements
+
+Node ≥ 22.13 (uses the global `fetch`).
+
+## License
+
+MIT — see the [repository](https://github.com/ShavitR/querais).

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { QueraisClient } from './client.js';
+const baseUrl = process.env.QUERAIS_BASE_URL ?? 'http://127.0.0.1:8787';
+const apiKey = process.env.QUERAIS_API_KEY ?? 'sk-querais-dev';
+const model = process.env.QUERAIS_MODEL ?? 'gemma3:4b';
+function usage() {
+    console.log('querais <command>');
+    console.log('  chat <prompt...>   stream a chat completion');
+    console.log('  models             list available models');
+    console.log('  nodes              list active nodes');
+    console.log('  stats              network stats');
+    console.log('  env: QUERAIS_BASE_URL, QUERAIS_API_KEY, QUERAIS_MODEL');
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    const client = new QueraisClient({ baseUrl, apiKey });
+    switch (cmd) {
+        case 'chat': {
+            const prompt = rest.join(' ');
+            if (!prompt) {
+                console.error('usage: querais chat <prompt>');
+                process.exit(1);
+            }
+            const messages = [{ role: 'user', content: prompt }];
+            for await (const delta of client.chatStream(messages, { model })) {
+                process.stdout.write(delta);
+            }
+            process.stdout.write('\n');
+            break;
+        }
+        case 'models':
+            console.log((await client.models()).join('\n') || '(none)');
+            break;
+        case 'nodes':
+            console.log(JSON.stringify(await client.nodes(), null, 2));
+            break;
+        case 'stats':
+            console.log(JSON.stringify(await client.stats(), null, 2));
+            break;
+        default:
+            usage();
+    }
+}
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,uBAAuB,CAAC;AACxE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,gBAAgB,CAAC;AAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,WAAW,CAAC;AAEvD,SAAS,KAAK;IACZ,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACjC,OAAO,CAAC,GAAG,CAAC,+CAA+C,CAAC,CAAC;IAC7D,OAAO,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;IAC1D,OAAO,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;IACtD,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;IAClD,OAAO,CAAC,GAAG,CAAC,yDAAyD,CAAC,CAAC;AACzE,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAEtD,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC9B,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;gBAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YACD,MAAM,QAAQ,GAAkB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YACpE,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;gBACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC9B,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC3B,MAAM;QACR,CAAC;QACD,KAAK,QAAQ;YACX,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,CAAC;YAC5D,MAAM;QACR,KAAK,OAAO;YACV,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YAC3D,MAAM;QACR,KAAK,OAAO;YACV,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YAC3D,MAAM;QACR;YACE,KAAK,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;IAC1B,OAAO,CAAC,KAAK,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,108 @@
+import { type ChatMessage } from '@querais/shared';
+export interface QueraisClientOptions {
+    /** Gateway base URL, e.g. http://127.0.0.1:8787 */
+    baseUrl: string;
+    /** Bearer API key. */
+    apiKey: string;
+    /** Optional requester private key — only needed to open a batched-settlement session. */
+    privateKey?: `0x${string}`;
+}
+/** What the gateway needs you to know to sign a spending cap (`GET /v1/credit/info`). */
+export interface CreditInfo {
+    chainId: number;
+    creditAccount: `0x${string}`;
+    token: `0x${string}`;
+    settler: `0x${string}`;
+}
+export interface OpenSessionOptions {
+    /** Cumulative ceiling the gateway may settle against this session (wei). */
+    maxSpendWei: bigint;
+    /** Session nonce (namespaces independent caps for the same requester). */
+    nonce: bigint;
+    /** Unix-seconds expiry; the gateway/contract reject the cap after this. */
+    deadline: bigint;
+}
+/** GET /v1/sessions — live session/credit/headroom view. Wei as decimal strings. */
+export interface SessionStatus {
+    requester: `0x${string}`;
+    settler: `0x${string}`;
+    session: {
+        nonce: string;
+        maxSpendWei: string;
+        deadline: string;
+        spentAgainstWei: string;
+        capRemainingWei: string;
+    } | null;
+    credit: {
+        balanceWei: string;
+    };
+    pendingDebits: {
+        count: number;
+        totalWei: string;
+    };
+    headroomWei: string | null;
+}
+export interface ChatOptions {
+    model: string;
+    maxTokens?: number;
+    temperature?: number;
+    /** QueraIS routing extensions. */
+    maxPricePer1kTokens?: number;
+    minReputation?: number;
+}
+export interface ChatResult {
+    content: string;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    jobId: string | null;
+}
+export interface NodeInfo {
+    wallet: string;
+    nodeId: string;
+    reputation: number;
+    models: Array<{
+        model: string;
+        pricePerTokenWei: string;
+        tokensPerSecond: number;
+    }>;
+}
+/**
+ * A tiny OpenAI-shaped client for the QueraIS gateway. The gateway is itself
+ * OpenAI-compatible, so this is convenience sugar (plus QueraIS-specific helpers
+ * like nodes()/stats()); the official `openai` SDK also works against the gateway.
+ */
+export declare class QueraisClient {
+    private readonly opts;
+    constructor(opts: QueraisClientOptions);
+    private headers;
+    private body;
+    /** Buffered chat completion. */
+    chat(messages: ChatMessage[], opts: ChatOptions): Promise<ChatResult>;
+    /** Streaming chat completion — yields content deltas as they arrive. */
+    chatStream(messages: ChatMessage[], opts: ChatOptions): AsyncGenerator<string>;
+    models(): Promise<string[]>;
+    nodes(): Promise<NodeInfo[]>;
+    stats(): Promise<unknown>;
+    /** Fetch the data needed to build + sign a spending cap (chainId, contract, settler). */
+    creditInfo(): Promise<CreditInfo>;
+    /**
+     * Open a batched-settlement session: sign an EIP-712 spending cap with the client's
+     * private key (signed once, off-chain, zero gas) and register it with the gateway. After
+     * this, jobs from this key settle in batches — no per-call wallet tx. Requires `privateKey`
+     * in the client options and a CreditAccount deposit already in place.
+     */
+    openSession(opts: OpenSessionOptions): Promise<{
+        ok: boolean;
+        nonce: string;
+    }>;
+    /**
+     * The requester's live session status: active cap (if any), on-chain spend against it,
+     * credit balance, unflushed debits, and `headroomWei` — the largest worst-case job cost
+     * the gateway would still accept right now (null without an active session).
+     */
+    sessionStatus(): Promise<SessionStatus>;
+}
+//# 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":"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"}

package/dist/client.js

@@ -0,0 +1,143 @@
+import { buildSignedSession } from '@querais/shared';
+/**
+ * A tiny OpenAI-shaped client for the QueraIS gateway. The gateway is itself
+ * OpenAI-compatible, so this is convenience sugar (plus QueraIS-specific helpers
+ * like nodes()/stats()); the official `openai` SDK also works against the gateway.
+ */
+export class QueraisClient {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    headers() {
+        return { 'content-type': 'application/json', authorization: `Bearer ${this.opts.apiKey}` };
+    }
+    body(messages, opts, stream) {
+        return JSON.stringify({
+            model: opts.model,
+            messages,
+            stream,
+            ...(opts.maxTokens !== undefined ? { max_tokens: opts.maxTokens } : {}),
+            ...(opts.temperature !== undefined ? { temperature: opts.temperature } : {}),
+            ...(opts.maxPricePer1kTokens !== undefined
+                ? { max_price_per_1k_tokens: opts.maxPricePer1kTokens }
+                : {}),
+            ...(opts.minReputation !== undefined ? { min_reputation: opts.minReputation } : {}),
+        });
+    }
+    /** Buffered chat completion. */
+    async chat(messages, opts) {
+        const res = await fetch(`${this.opts.baseUrl}/v1/chat/completions`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: this.body(messages, opts, false),
+        });
+        if (!res.ok)
+            throw new Error(`QueraIS chat failed: HTTP ${res.status} ${await res.text()}`);
+        const json = (await res.json());
+        return {
+            content: json.choices[0]?.message.content ?? '',
+            usage: json.usage,
+            jobId: res.headers.get('x-querais-job-id'),
+        };
+    }
+    /** Streaming chat completion — yields content deltas as they arrive. */
+    async *chatStream(messages, opts) {
+        const res = await fetch(`${this.opts.baseUrl}/v1/chat/completions`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: this.body(messages, opts, true),
+        });
+        if (!res.ok || !res.body) {
+            throw new Error(`QueraIS chat stream failed: HTTP ${res.status} ${await res.text()}`);
+        }
+        const reader = res.body.getReader();
+        const dec = new TextDecoder();
+        let buf = '';
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buf += dec.decode(value, { stream: true });
+            let i;
+            while ((i = buf.indexOf('\n\n')) !== -1) {
+                const frame = buf.slice(0, i);
+                buf = buf.slice(i + 2);
+                const data = frame.replace(/^data: /, '').trim();
+                if (!data || data === '[DONE]')
+                    continue;
+                try {
+                    const j = JSON.parse(data);
+                    const delta = j.choices?.[0]?.delta?.content;
+                    if (delta)
+                        yield delta;
+                }
+                catch {
+                    /* ignore keep-alives / non-JSON frames */
+                }
+            }
+        }
+    }
+    async models() {
+        const res = await fetch(`${this.opts.baseUrl}/v1/models`, { headers: this.headers() });
+        const json = (await res.json());
+        return json.data.map((m) => m.id);
+    }
+    async nodes() {
+        const res = await fetch(`${this.opts.baseUrl}/v1/nodes`, { headers: this.headers() });
+        const json = (await res.json());
+        return json.data;
+    }
+    async stats() {
+        const res = await fetch(`${this.opts.baseUrl}/v1/stats`, { headers: this.headers() });
+        return res.json();
+    }
+    /** Fetch the data needed to build + sign a spending cap (chainId, contract, settler). */
+    async creditInfo() {
+        const res = await fetch(`${this.opts.baseUrl}/v1/credit/info`, { headers: this.headers() });
+        if (!res.ok)
+            throw new Error(`QueraIS credit info failed: HTTP ${res.status}`);
+        return (await res.json());
+    }
+    /**
+     * Open a batched-settlement session: sign an EIP-712 spending cap with the client's
+     * private key (signed once, off-chain, zero gas) and register it with the gateway. After
+     * this, jobs from this key settle in batches — no per-call wallet tx. Requires `privateKey`
+     * in the client options and a CreditAccount deposit already in place.
+     */
+    async openSession(opts) {
+        if (!this.opts.privateKey)
+            throw new Error('openSession requires a privateKey in client opts');
+        const info = await this.creditInfo();
+        const wire = await buildSignedSession(this.opts.privateKey, {
+            maxSpendWei: opts.maxSpendWei,
+            nonce: opts.nonce,
+            deadline: opts.deadline,
+            settler: info.settler,
+            chainId: info.chainId,
+            verifyingContract: info.creditAccount,
+        });
+        const res = await fetch(`${this.opts.baseUrl}/v1/sessions`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(wire),
+        });
+        if (!res.ok) {
+            throw new Error(`QueraIS openSession failed: HTTP ${res.status} ${await res.text()}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * The requester's live session status: active cap (if any), on-chain spend against it,
+     * credit balance, unflushed debits, and `headroomWei` — the largest worst-case job cost
+     * the gateway would still accept right now (null without an active session).
+     */
+    async sessionStatus() {
+        const res = await fetch(`${this.opts.baseUrl}/v1/sessions`, { headers: this.headers() });
+        if (!res.ok) {
+            throw new Error(`QueraIS sessionStatus failed: HTTP ${res.status} ${await res.text()}`);
+        }
+        return (await res.json());
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @querais/sdk — a tiny OpenAI-shaped TypeScript client + `querais` CLI.
+ *
+ * The QueraIS gateway is OpenAI-compatible, so the official `openai` SDK works
+ * against it directly (see the e2e parity test). This client adds convenience plus
+ * QueraIS-specific helpers (nodes(), stats()).
+ */
+export declare const SDK_VERSION = "0.2.0";
+export { QueraisClient, type QueraisClientOptions, type ChatOptions, type ChatResult, type NodeInfo, type SessionStatus, } from './client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @querais/sdk — a tiny OpenAI-shaped TypeScript client + `querais` CLI.
+ *
+ * The QueraIS gateway is OpenAI-compatible, so the official `openai` SDK works
+ * against it directly (see the e2e parity test). This client adds convenience plus
+ * QueraIS-specific helpers (nodes(), stats()).
+ */
+export const SDK_VERSION = '0.2.0';
+export { QueraisClient, } from './client.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC,OAAO,EACL,aAAa,GAMd,MAAM,aAAa,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@querais/sdk",
+  "version": "0.2.0",
+  "license": "MIT",
+  "description": "TypeScript client + CLI for QueraIS, the decentralized AI inference marketplace. OpenAI-shaped chat/streaming plus QueraIS extras: nodes, stats, batched-settlement sessions.",
+  "keywords": [
+    "querais",
+    "ai",
+    "llm",
+    "inference",
+    "openai-compatible",
+    "decentralized",
+    "arbitrum",
+    "web3"
+  ],
+  "homepage": "https://github.com/ShavitR/querais/tree/main/packages/sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShavitR/querais.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/ShavitR/querais/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "querais": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/.tsbuildinfo",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "dependencies": {
+    "@querais/shared": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test \"src/**/*.test.ts\""
+  }
+}