versera-app 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# versera
+
+Official JavaScript/TypeScript SDK for [Versera](https://versera.dev) — prompt version control for LLM apps.
+
+## Installation
+
+```bash
+npm install versera-app
+```
+
+## Quick start
+
+```typescript
+import { Versera } from 'versera-app'
+
+const versera = new Versera({
+  apiKey: process.env.VERSERA_API_KEY!
+})
+
+// Resolve a prompt at runtime
+const { template } = await versera.resolve(
+  'summarize-doc',
+  {
+    tone: 'professional',
+    document: userDocument
+  }
+)
+
+// Use with any LLM
+const response = await anthropic.messages.create({
+  model: 'claude-sonnet-4-6',
+  messages: [{ role: 'user', content: template }]
+})
+```
+
+## Methods
+
+### versera.resolve(slug, variables?, options?)
+Resolves a prompt template with variables. Costs 1 credit per call.
+
+### versera.push(input)
+Creates or updates a prompt.
+
+### versera.list(options?)
+Lists all your prompts.
+
+### versera.get(slug)
+Gets a single prompt with version history.
+
+### versera.saveVersion(slug, input)
+Saves a new version of a prompt.
+
+### versera.rollback(slug, version)
+Rolls back to a previous version.
+
+### versera.log(input)
+Logs a quality score for A/B testing.
+
+## Error handling
+
+```typescript
+import { Versera, VerseraError } from 'versera'
+
+try {
+  const { template } = await versera.resolve(
+    'my-prompt'
+  )
+} catch (error) {
+  if (error instanceof VerseraError) {
+    if (error.status === 402) {
+      console.log('Out of credits!')
+    }
+    if (error.status === 404) {
+      console.log('Prompt not found')
+    }
+  }
+}
+```
+
+## License
+MIT

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+export interface VerseraConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface ResolveOptions {
+    environment?: 'dev' | 'staging' | 'prod';
+    [key: string]: string | undefined;
+}
+export interface ResolveResponse {
+    versionId: string;
+    template: string;
+    variables: string[];
+    promptSlug: string;
+    environment: string;
+    resolvedAt: string;
+}
+export interface PromptInput {
+    name: string;
+    environment: 'dev' | 'staging' | 'prod';
+    template: string;
+    message?: string;
+}
+export interface PromptResponse {
+    id: string;
+    slug: string;
+    name: string;
+    environment: string;
+    status: string;
+    versions: VersionResponse[];
+}
+export interface VersionResponse {
+    id: string;
+    version: number;
+    isCurrent: boolean;
+    message: string;
+    template: string;
+    diff: string[];
+    savedAt: string;
+}
+export declare class VerseraError extends Error {
+    status: number;
+    code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+export declare class Versera {
+    private apiKey;
+    private baseUrl;
+    constructor(config: VerseraConfig);
+    private request;
+    resolve(promptSlug: string, variables?: Record<string, string>, options?: {
+        environment?: 'dev' | 'staging' | 'prod';
+    }): Promise<ResolveResponse>;
+    push(input: PromptInput): Promise<PromptResponse>;
+    list(options?: {
+        search?: string;
+        environment?: string;
+    }): Promise<PromptResponse[]>;
+    get(slug: string): Promise<PromptResponse>;
+    saveVersion(slug: string, input: {
+        template: string;
+        message?: string;
+    }): Promise<VersionResponse>;
+    rollback(slug: string, version: number): Promise<VersionResponse>;
+    log(input: {
+        versionId: string;
+        score?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+}
+export default Versera;
+//# 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":"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"}

package/dist/index.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Versera = exports.VerseraError = void 0;
+class VerseraError extends Error {
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'VerseraError';
+    }
+}
+exports.VerseraError = VerseraError;
+class Versera {
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new VerseraError('API key is required', 400);
+        }
+        if (!config.apiKey.startsWith('vrs_')) {
+            throw new VerseraError('Invalid API key format. ' +
+                'Key must start with vrs_', 400);
+        }
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl ??
+            'https://api.versera.dev';
+    }
+    async request(path, options = {}) {
+        const url = `${this.baseUrl}${path}`;
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+                ...options.headers
+            }
+        });
+        if (!response.ok) {
+            const error = await response.json()
+                .catch(() => ({
+                error: 'Unknown error'
+            }));
+            throw new VerseraError(error.error ?? 'Request failed', response.status);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        return response.json();
+    }
+    async resolve(promptSlug, variables, options) {
+        const params = new URLSearchParams();
+        if (options?.environment) {
+            params.set('env', options.environment);
+        }
+        if (variables) {
+            Object.entries(variables).forEach(([key, value]) => {
+                params.set(key, value);
+            });
+        }
+        const query = params.toString();
+        const path = `/v1/resolve/${promptSlug}` +
+            (query ? `?${query}` : '');
+        return this.request(path);
+    }
+    async push(input) {
+        return this.request('/v1/prompts', {
+            method: 'POST',
+            body: JSON.stringify(input)
+        });
+    }
+    async list(options) {
+        const params = new URLSearchParams();
+        if (options?.search) {
+            params.set('search', options.search);
+        }
+        if (options?.environment) {
+            params.set('environment', options.environment);
+        }
+        const query = params.toString();
+        const path = '/v1/prompts' +
+            (query ? `?${query}` : '');
+        return this.request(path);
+    }
+    async get(slug) {
+        return this.request(`/v1/prompts/${slug}`);
+    }
+    async saveVersion(slug, input) {
+        return this.request(`/v1/prompts/${slug}/versions`, {
+            method: 'POST',
+            body: JSON.stringify(input)
+        });
+    }
+    async rollback(slug, version) {
+        return this.request(`/v1/prompts/${slug}/versions/${version}/rollback`, { method: 'POST' });
+    }
+    async log(input) {
+        return this.request('/v1/prompts/log', {
+            method: 'POST',
+            body: JSON.stringify(input)
+        });
+    }
+}
+exports.Versera = Versera;
+exports.default = Versera;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AA6CA,MAAa,YAAa,SAAQ,KAAK;IACrC,YACE,OAAe,EACR,MAAc,EACd,IAAa;QAEpB,KAAK,CAAC,OAAO,CAAC,CAAA;QAHP,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAS;QAGpB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAA;IAC5B,CAAC;CACF;AATD,oCASC;AAED,MAAa,OAAO;IAIlB,YAAY,MAAqB;QAC/B,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,IAAI,YAAY,CACpB,qBAAqB,EACrB,GAAG,CACJ,CAAA;QACH,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,YAAY,CACpB,0BAA0B;gBAC1B,0BAA0B,EAC1B,GAAG,CACJ,CAAA;QACH,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAA;QAC3B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO;YAC3B,yBAAyB,CAAA;IAC7B,CAAC;IAEO,KAAK,CAAC,OAAO,CACnB,IAAY,EACZ,UAAuB,EAAE;QAEzB,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,CAAA;QACpC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,GAAG,OAAO;YACV,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,WAAW,EAAE,IAAI,CAAC,MAAM;gBACxB,GAAG,OAAO,CAAC,OAAO;aACnB;SACF,CAAC,CAAA;QAEF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE;iBAChC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;gBACZ,KAAK,EAAE,eAAe;aACvB,CAAC,CAAC,CAAA;YACL,MAAM,IAAI,YAAY,CACpB,KAAK,CAAC,KAAK,IAAI,gBAAgB,EAC/B,QAAQ,CAAC,MAAM,CAChB,CAAA;QACH,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,OAAO,SAAc,CAAA;QACvB,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAA;IACxB,CAAC;IAED,KAAK,CAAC,OAAO,CACX,UAAkB,EAClB,SAAkC,EAClC,OAGC;QAED,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAA;QAEpC,IAAI,OAAO,EAAE,WAAW,EAAE,CAAC;YACzB,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;QACxC,CAAC;QAED,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,OAAO,CAC/B,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;gBACf,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YACxB,CAAC,CACF,CAAA;QACH,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAA;QAC/B,MAAM,IAAI,GAAG,eAAe,UAAU,EAAE;YACtC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QAE5B,OAAO,IAAI,CAAC,OAAO,CAAkB,IAAI,CAAC,CAAA;IAC5C,CAAC;IAED,KAAK,CAAC,IAAI,CACR,KAAkB;QAElB,OAAO,IAAI,CAAC,OAAO,CACjB,aAAa,EACb;YACE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;SAC5B,CACF,CAAA;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAGV;QACC,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAA;QACpC,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;YACpB,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;QACtC,CAAC;QACD,IAAI,OAAO,EAAE,WAAW,EAAE,CAAC;YACzB,MAAM,CAAC,GAAG,CACR,aAAa,EACb,OAAO,CAAC,WAAW,CACpB,CAAA;QACH,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAA;QAC/B,MAAM,IAAI,GAAG,aAAa;YACxB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAmB,IAAI,CAAC,CAAA;IAC7C,CAAC;IAED,KAAK,CAAC,GAAG,CACP,IAAY;QAEZ,OAAO,IAAI,CAAC,OAAO,CACjB,eAAe,IAAI,EAAE,CACtB,CAAA;IACH,CAAC;IAED,KAAK,CAAC,WAAW,CACf,IAAY,EACZ,KAGC;QAED,OAAO,IAAI,CAAC,OAAO,CACjB,eAAe,IAAI,WAAW,EAC9B;YACE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;SAC5B,CACF,CAAA;IACH,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,IAAY,EACZ,OAAe;QAEf,OAAO,IAAI,CAAC,OAAO,CACjB,eAAe,IAAI,aAAa,OAAO,WAAW,EAClD,EAAE,MAAM,EAAE,MAAM,EAAE,CACnB,CAAA;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAIT;QACC,OAAO,IAAI,CAAC,OAAO,CACjB,iBAAiB,EACjB;YACE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;SAC5B,CACF,CAAA;IACH,CAAC;CACF;AAnKD,0BAmKC;AAED,kBAAe,OAAO,CAAA"}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "versera-app",
+  "version": "0.1.0",
+  "description": "Official JavaScript SDK for the Versera prompt version control API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node test.js"
+  },
+  "keywords": [
+    "versera", "prompt", "llm",
+    "version-control", "ai"
+  ],
+  "author": "Versera",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}