@sourcerly/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Garcia Patodo, LLC (Sourcerly)
+
+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,18 @@
-# Temporary Holding Version
+# @sourcerly/sdk (TypeScript / JavaScript)
 
-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.
+```sh
+npm install @sourcerly/sdk
+```
+
+Node 18 or newer. This is an ES module package: use `import`, or `const { Sourcerly } = await import("@sourcerly/sdk")` from CommonJS (`require` does not work).
+
+```ts
+import { Sourcerly } from "@sourcerly/sdk";
+
+const client = new Sourcerly({ apiKey: process.env.SOURCERLY_API_KEY! });
+const response = await client.ask({ input: "Can I cancel? Will I get a refund?" });
+for (const r of response.results) console.log(r.status, r.answer ?? r.message);
+```
+
+`client.ask({ questions: [{ id: "refund", question: "..." }] })` sends explicit questions, `client.stream(...)` yields each result as soon as it is ready.
+Retries reuse one `Idempotency-Key`, so a retried request is answered and counted once. No dependencies (uses `fetch`). Tests: `npm test`.

package/dist/src/index.d.ts

@@ -0,0 +1,96 @@
+export type EvidenceStatus = "supported" | "partial" | "insufficient" | "conflicting" | "not_evaluated";
+export interface Citation {
+    sourceId: string | null;
+    sourceName: string;
+    page: number | null;
+    reference: string | null;
+}
+export interface Result {
+    id: string;
+    question: string;
+    status: EvidenceStatus;
+    answerable: boolean;
+    answer: string | null;
+    message: string | null;
+    language: string | null;
+    citations: Citation[];
+}
+export interface AskResponse {
+    id: string;
+    object: "sourcerly.answer";
+    status: "completed" | "partial";
+    livemode: boolean;
+    createdAt: string;
+    language: string | null;
+    conversationId: string | null;
+    results: Result[];
+    summary: {
+        questions: number;
+        supported: number;
+        partial: number;
+        insufficient: number;
+        conflicting: number;
+        notEvaluated: number;
+    };
+    usage: {
+        questions: number;
+    };
+}
+export type Question = string | {
+    id?: string;
+    question: string;
+};
+export interface AskOptions {
+    idempotencyKey?: string;
+    citations?: boolean;
+    conversationId?: string;
+}
+export type AskInput = ({
+    input: string;
+} | {
+    questions: Question[];
+}) & AskOptions;
+export interface StreamEvent {
+    event: string;
+    data: any;
+}
+export interface SourcerlyOptions {
+    apiKey: string;
+    baseUrl?: string; /** Streaming is served by the Sourcerly backend (the public API does not stream). */
+    streamBaseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    fetch?: typeof fetch;
+}
+/** The API refused or failed the request. `status` is the HTTP status, `code` the machine-readable code (for example BAD_REQUEST). */
+export declare class SourcerlyError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined, retryAfter?: number | undefined);
+}
+/** 401 or 403: the key is missing, invalid, revoked, expired, or its channel is disabled. */
+export declare class SourcerlyAuthError extends SourcerlyError {
+}
+/** 429 RATE_LIMITED: too many requests. `retryAfter` is how many seconds to wait. */
+export declare class SourcerlyRateLimitError extends SourcerlyError {
+}
+/** 429 QUESTION_LIMIT_EXCEEDED: the plan's monthly questions are used up. Retrying will not help until the next period or an upgrade. */
+export declare class SourcerlyQuotaError extends SourcerlyError {
+}
+export declare class Sourcerly {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly streamBaseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(options: SourcerlyOptions);
+    /** Free text (`input`) that may hold several questions, or explicit `questions` (strings, or {id, question} to keep your own ids). */
+    ask(request: AskInput | string): Promise<AskResponse>;
+    /** Each event as it arrives. Every `question.completed` is a finished, cited, evidence-checked result. */
+    stream(request: AskInput | string): AsyncGenerator<StreamEvent>;
+    private body;
+    private post;
+    private error;
+}

package/dist/src/index.js

@@ -0,0 +1,134 @@
+// Small client for POST /v1/ask on the Sourcerly public API. No dependencies: it uses the platform's fetch (Node 18+, browsers' server-side runtimes).
+//
+//   const client = new Sourcerly({ apiKey: process.env.SOURCERLY_API_KEY! });
+//   const response = await client.ask({ input: "Can I cancel? Will I get a refund?" });
+//   for (const r of response.results) console.log(r.status, r.answer ?? r.message);
+/** The API refused or failed the request. `status` is the HTTP status, `code` the machine-readable code (for example BAD_REQUEST). */
+export class SourcerlyError extends Error {
+    status;
+    code;
+    retryAfter;
+    constructor(message, status, code, retryAfter) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfter = retryAfter;
+        this.name = new.target.name;
+    }
+}
+/** 401 or 403: the key is missing, invalid, revoked, expired, or its channel is disabled. */
+export class SourcerlyAuthError extends SourcerlyError {
+}
+/** 429 RATE_LIMITED: too many requests. `retryAfter` is how many seconds to wait. */
+export class SourcerlyRateLimitError extends SourcerlyError {
+}
+/** 429 QUESTION_LIMIT_EXCEEDED: the plan's monthly questions are used up. Retrying will not help until the next period or an upgrade. */
+export class SourcerlyQuotaError extends SourcerlyError {
+}
+const DEFAULT_BASE_URL = "https://public-api.sourcerly.io";
+const DEFAULT_STREAM_BASE_URL = "https://api.sourcerly.io/msp-sourcerly";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class Sourcerly {
+    apiKey;
+    baseUrl;
+    streamBaseUrl;
+    timeoutMs;
+    maxRetries;
+    fetchImpl;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error("apiKey is required");
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.streamBaseUrl = (options.streamBaseUrl ?? DEFAULT_STREAM_BASE_URL).replace(/\/+$/, "");
+        this.timeoutMs = options.timeoutMs ?? 60_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    /** Free text (`input`) that may hold several questions, or explicit `questions` (strings, or {id, question} to keep your own ids). */
+    async ask(request) {
+        const body = this.body(typeof request === "string" ? { input: request } : request);
+        // One key for every attempt: a retry after a timeout is the same logical request, answered and counted once.
+        const key = (typeof request === "string" ? undefined : request.idempotencyKey) ?? crypto.randomUUID();
+        for (let attempt = 0;; attempt++) {
+            try {
+                const response = await this.post("/v1/ask", body, key, "application/json");
+                if (response.ok)
+                    return (await response.json());
+                const error = await this.error(response);
+                const retryable = [409, 429, 500, 502, 503, 504].includes(response.status) && !(error instanceof SourcerlyQuotaError);
+                if (!retryable || attempt >= this.maxRetries)
+                    throw error;
+                await sleep((error.retryAfter ?? Math.min(2 ** attempt * 0.5, 8)) * 1000);
+            }
+            catch (e) {
+                if (e instanceof SourcerlyError)
+                    throw e;
+                if (attempt >= this.maxRetries)
+                    throw new SourcerlyError(`Could not reach Sourcerly: ${e.message}`);
+                await sleep(Math.min(2 ** attempt * 0.5, 8) * 1000);
+            }
+        }
+    }
+    /** Each event as it arrives. Every `question.completed` is a finished, cited, evidence-checked result. */
+    async *stream(request) {
+        const r = typeof request === "string" ? { input: request } : request;
+        const response = await this.post("/api/v1/ask/stream", this.body(r), r.idempotencyKey ?? crypto.randomUUID(), "text/event-stream", this.streamBaseUrl);
+        if (!response.ok)
+            throw await this.error(response);
+        const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+        let buffer = "";
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                return;
+            buffer += value;
+            let end;
+            while ((end = buffer.search(/\r?\n\r?\n/)) >= 0) {
+                const block = buffer.slice(0, end);
+                buffer = buffer.slice(end).replace(/^\r?\n\r?\n/, "");
+                let event = "", data = "";
+                for (const line of block.split(/\r?\n/)) {
+                    if (line.startsWith("event:"))
+                        event = line.slice(6).trim();
+                    else if (line.startsWith("data:"))
+                        data += line.slice(5).trimStart();
+                }
+                if (event)
+                    yield { event, data: data ? JSON.parse(data) : null };
+            }
+        }
+    }
+    body(r) {
+        const body = "input" in r
+            ? { input: r.input }
+            : { questions: r.questions.map((q) => (typeof q === "string" ? { question: q } : q)) };
+        if (r.citations === false)
+            body.response = { citations: false };
+        if (r.conversationId)
+            body.conversationId = r.conversationId;
+        return JSON.stringify(body);
+    }
+    post(path, body, idempotencyKey, accept, base = this.baseUrl) {
+        return this.fetchImpl(base + path, {
+            method: "POST", body, signal: AbortSignal.timeout(this.timeoutMs),
+            headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json", Accept: accept, "Idempotency-Key": idempotencyKey },
+        });
+    }
+    async error(response) {
+        let payload = {};
+        try {
+            payload = await response.json();
+        }
+        catch { /* not JSON */ }
+        const message = payload.message ?? response.statusText ?? "Request failed", code = payload.code;
+        const header = response.headers.get("Retry-After"), retryAfter = header ? Number(header) : undefined;
+        if (response.status === 401 || response.status === 403)
+            return new SourcerlyAuthError(message, response.status, code);
+        if (response.status === 429 && code === "QUESTION_LIMIT_EXCEEDED")
+            return new SourcerlyQuotaError(message, response.status, code);
+        if (response.status === 429)
+            return new SourcerlyRateLimitError(message, response.status, code, retryAfter);
+        return new SourcerlyError(message, response.status, code, retryAfter);
+    }
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@sourcerly/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "TypeScript client for the Sourcerly API: grounded, cited answers from your own knowledge.",
+  "keywords": [
+    "sourcerly",
+    "rag",
+    "knowledge",
+    "answers",
+    "citations",
+    "sdk"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/sourcerly/apis/sourcerly-sdk.git",
+    "directory": "typescript"
+  },
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "tsc -p . && node --test dist/test/client.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}