@brandazine/solari-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandazine
+
+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,40 @@
+# @brandazine/solari-sdk
+
+TypeScript client for the [SOLARI API](https://solari.sh/api) — creator and brand intelligence across Instagram and TikTok. Zero dependencies; runs on Node 18+, Bun, Deno, Cloudflare Workers, and browsers with `fetch`.
+
+```
+npm install @brandazine/solari-sdk
+```
+
+## Quickstart
+
+```ts
+import { Solari } from "@brandazine/solari-sdk";
+
+const solari = new Solari({ token: process.env.SOLARI_TOKEN });
+
+const hits = await solari.tools.catalog.instagram.account.search({ query: "nike", limit: 3 });
+const brand = await solari.call("solari_insight_instagram_brand_overview", { username: "nike" });
+const tools = await solari.listTools();
+```
+
+Get a token with `solari auth token` on a machine that is signed in to the [solari CLI](https://solari.sh/docs), or pass a token you already hold from an MCP connector. With no `token` option the client reads `SOLARI_TOKEN`.
+
+## API
+
+- `new Solari({ token?, baseUrl?, fetch?, timeoutMs?, userAgent? })` — `baseUrl` defaults to `https://solari.sh`; `fetch` lets you inject a custom implementation.
+- `solari.listTools()` — every tool the signed-in account can call, with its JSON input schema.
+- `solari.getTool(name)` — one tool.
+- `solari.call(name, args)` — run a tool and get its JSON payload back. Typed as `call<T>()`.
+- `solari.tools.<family>.<platform>.<group>.<name>(args)` — the same call spelled as a path; segments join with `_` under the `solari_` prefix. The path is dynamic, so it is not type-checked against the live tool list.
+- `solari.me()` — the identity behind the token.
+
+Errors throw `SolariError` with `status`, `code`, `message`, `tool`, `retryAfterSeconds`, and a `retryable` flag (429, 502, 503, 504). Codes come straight from the API: `invalid_arguments`, `tool_not_found`, `rate_limited`, `forbidden`, `upstream_timeout`, `app_warming_up`, ...
+
+## Development
+
+```
+bun install
+bun test
+bun run build
+```

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+export declare const DEFAULT_BASE_URL = "https://solari.sh";
+export declare const API_PREFIX = "/mcp/api/v1";
+export declare const SDK_VERSION = "0.1.0";
+export declare const TOKEN_ENV = "SOLARI_TOKEN";
+export interface SolariTool {
+    name: string;
+    title: string | null;
+    description: string | null;
+    input_schema: Record<string, unknown>;
+    annotations: Record<string, unknown> | null;
+}
+export interface SolariIdentity {
+    sub: string;
+    email?: string;
+    name?: string;
+    client?: {
+        kind: string;
+        name?: string;
+    };
+}
+export interface SolariOptions {
+    token?: string | undefined;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    userAgent?: string;
+}
+export type ToolArguments = Record<string, unknown>;
+export interface ToolPath {
+    (args?: ToolArguments): Promise<unknown>;
+    [segment: string]: ToolPath;
+}
+export declare class SolariError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly tool: string | undefined;
+    readonly retryAfterSeconds: number | undefined;
+    constructor(input: {
+        status: number;
+        code: string;
+        message: string;
+        tool?: string;
+        retryAfterSeconds?: number;
+    });
+    get retryable(): boolean;
+}
+export declare function normalizeBaseUrl(raw: string): string;
+export declare function toolName(segments: readonly string[]): string;
+export declare class Solari {
+    readonly baseUrl: string;
+    readonly tools: ToolPath;
+    private readonly token;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly userAgent;
+    constructor(options?: SolariOptions);
+    listTools(): Promise<SolariTool[]>;
+    getTool(name: string): Promise<SolariTool>;
+    call<T = unknown>(name: string, args?: ToolArguments): Promise<T>;
+    me(): Promise<SolariIdentity>;
+    private toolPath;
+    private request;
+}
+export default Solari;

package/dist/index.js

@@ -0,0 +1,180 @@
+export const DEFAULT_BASE_URL = "https://solari.sh";
+export const API_PREFIX = "/mcp/api/v1";
+export const SDK_VERSION = "0.1.0";
+export const TOKEN_ENV = "SOLARI_TOKEN";
+const DEFAULT_TIMEOUT_MS = 150_000;
+export class SolariError extends Error {
+    status;
+    code;
+    tool;
+    retryAfterSeconds;
+    constructor(input) {
+        super(input.message);
+        this.name = "SolariError";
+        this.status = input.status;
+        this.code = input.code;
+        this.tool = input.tool;
+        this.retryAfterSeconds = input.retryAfterSeconds;
+    }
+    get retryable() {
+        return this.status === 429 || this.status === 503 || this.status === 502 || this.status === 504;
+    }
+}
+function tokenFromEnvironment() {
+    const env = globalThis.process?.env;
+    const raw = env?.[TOKEN_ENV]?.trim();
+    return raw ? raw : undefined;
+}
+export function normalizeBaseUrl(raw) {
+    const trimmed = raw.trim().replace(/\/+$/, "");
+    const withScheme = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+    const url = new URL(withScheme);
+    const path = url.pathname.replace(/\/+$/, "");
+    const withoutApi = path.endsWith(API_PREFIX) ? path.slice(0, -API_PREFIX.length) : path;
+    return `${url.origin}${withoutApi}`;
+}
+export function toolName(segments) {
+    const parts = segments.map((segment) => segment.trim()).filter((segment) => segment.length > 0);
+    if (parts.length === 0) {
+        throw new SolariError({ status: 0, code: "invalid_tool_path", message: "a tool path needs at least one segment" });
+    }
+    const joined = parts.join("_");
+    return joined === "solari" || joined.startsWith("solari_") ? joined : `solari_${joined}`;
+}
+async function parseErrorBody(response) {
+    const fallback = { code: `http_${response.status}`, message: `SOLARI API returned HTTP ${response.status}` };
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch {
+        return fallback;
+    }
+    if (!text) {
+        return fallback;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        const error = parsed.error;
+        if (error && typeof error === "object") {
+            return {
+                code: typeof error.code === "string" ? error.code : fallback.code,
+                message: typeof error.message === "string" ? error.message : fallback.message,
+                ...(typeof error.tool === "string" ? { tool: error.tool } : {}),
+            };
+        }
+        if (typeof parsed.error_description === "string") {
+            return {
+                code: typeof parsed.error === "string" ? String(parsed.error) : fallback.code,
+                message: parsed.error_description,
+            };
+        }
+    }
+    catch {
+        return { ...fallback, message: text.slice(0, 300) };
+    }
+    return fallback;
+}
+export class Solari {
+    baseUrl;
+    tools;
+    token;
+    fetchImpl;
+    timeoutMs;
+    userAgent;
+    constructor(options = {}) {
+        const token = options.token?.trim() || tokenFromEnvironment();
+        if (!token) {
+            throw new SolariError({
+                status: 0,
+                code: "missing_token",
+                message: `no access token: pass { token } or set ${TOKEN_ENV} (mint one with "solari auth token")`,
+            });
+        }
+        this.token = token;
+        this.baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.userAgent = options.userAgent ?? `solari-sdk-ts/${SDK_VERSION}`;
+        this.tools = this.toolPath([]);
+    }
+    async listTools() {
+        const body = (await this.request("GET", `${API_PREFIX}/tools`));
+        return body.tools ?? [];
+    }
+    async getTool(name) {
+        return (await this.request("GET", `${API_PREFIX}/tools/${encodeURIComponent(name)}`));
+    }
+    async call(name, args = {}) {
+        return (await this.request("POST", `${API_PREFIX}/tools/${encodeURIComponent(name)}`, args));
+    }
+    async me() {
+        return (await this.request("GET", `${API_PREFIX}/me`));
+    }
+    toolPath(segments) {
+        const invoke = (args = {}) => this.call(toolName(segments), args);
+        return new Proxy(invoke, {
+            get: (_target, property) => {
+                if (typeof property !== "string" || property === "then") {
+                    return undefined;
+                }
+                return this.toolPath([...segments, property]);
+            },
+            apply: (_target, _thisArg, argumentList) => invoke(argumentList[0]),
+        });
+    }
+    async request(method, path, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            Accept: "application/json",
+            "User-Agent": this.userAgent,
+        };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : null,
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            const aborted = error instanceof Error && error.name === "AbortError";
+            throw new SolariError({
+                status: 0,
+                code: aborted ? "timeout" : "network_error",
+                message: aborted
+                    ? `SOLARI API did not answer within ${Math.round(this.timeoutMs / 1000)}s`
+                    : `could not reach SOLARI API: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            const parsed = await parseErrorBody(response);
+            const retryAfter = Number(response.headers.get("retry-after") ?? "");
+            throw new SolariError({
+                status: response.status,
+                ...parsed,
+                ...(Number.isFinite(retryAfter) && retryAfter > 0 ? { retryAfterSeconds: retryAfter } : {}),
+            });
+        }
+        const text = await response.text();
+        if (!text) {
+            return null;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new SolariError({ status: response.status, code: "invalid_response", message: "SOLARI API returned non-JSON" });
+        }
+    }
+}
+export default Solari;

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@brandazine/solari-sdk",
+	"version": "0.1.0",
+	"description": "TypeScript client for the SOLARI API — creator and brand intelligence across Instagram and TikTok.",
+	"license": "MIT",
+	"homepage": "https://solari.sh/api",
+	"keywords": [
+		"solari",
+		"brandazine",
+		"instagram",
+		"tiktok",
+		"creator",
+		"influencer",
+		"brand",
+		"sdk",
+		"api-client"
+	],
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"sideEffects": false,
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.4.1",
+		"typescript": "^5.9.2"
+	},
+	"engines": {
+		"node": ">=18"
+	}
+}