plp-client 1.0.0

package/README.md

@@ -0,0 +1,214 @@
+# @plp/client
+
+[![PLP Compliant](https://img.shields.io/badge/PLP-Compliant-brightgreen)](https://github.com/gorealai/plp)
+[![npm version](https://img.shields.io/npm/v/@plp/client.svg)](https://www.npmjs.com/package/@plp/client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
+
+Official JavaScript/TypeScript client for **PLP (Prompt Library Protocol)**.
+
+## Installation
+
+```bash
+npm install @plp/client
+# or
+yarn add @plp/client
+# or
+pnpm add @plp/client
+```
+
+## Quick Start
+
+```typescript
+import { PLPClient } from '@plp/client';
+
+const client = new PLPClient('https://prompts.goreal.ai', {
+  apiKey: 'your-api-key' // Optional
+});
+
+// Get latest version of a prompt
+const prompt = await client.get('marketing/welcome-email');
+console.log(prompt.content); // "Hello {{name}}..."
+
+// Get specific version
+const oldPrompt = await client.get('marketing/welcome-email', '1.0.0');
+
+// Save a new prompt
+await client.put('support/faq-bot', {
+  content: 'You are a helpful FAQ bot. Answer: {{question}}',
+  meta: {
+    version: '1.0.0',
+    author: 'yoad'
+  }
+});
+
+// Delete a prompt
+await client.delete('deprecated/old-prompt');
+```
+
+## API Reference
+
+### `PLPClient`
+
+#### Constructor
+
+```typescript
+new PLPClient(baseUrl: string, options?: PLPClientOptions)
+```
+
+**Options:**
+- `apiKey?: string` - Optional Bearer token for authentication
+- `headers?: Record<string, string>` - Additional HTTP headers
+- `timeout?: number` - Request timeout in milliseconds (default: 10000)
+
+#### Methods
+
+##### `get(promptId, version?)`
+
+Retrieve a prompt by ID and optional version.
+
+```typescript
+async get(promptId: string, version?: string): Promise<PromptEnvelope>
+```
+
+- **`promptId`**: Unique prompt identifier (e.g., `"marketing/welcome-email"`)
+- **`version`**: Optional version string (e.g., `"1.2.0"`). If omitted, returns latest.
+
+**Returns:** `PromptEnvelope`
+
+**Throws:** `PLPError` if not found (404) or other errors
+
+##### `put(promptId, input)`
+
+Create or update a prompt (idempotent upsert).
+
+```typescript
+async put(promptId: string, input: PromptInput): Promise<PromptEnvelope>
+```
+
+- **`promptId`**: Unique prompt identifier
+- **`input`**: Object with `content` (string, required) and `meta` (object, optional)
+
+**Returns:** The saved `PromptEnvelope`
+
+##### `delete(promptId)`
+
+Delete a prompt and all its versions.
+
+```typescript
+async delete(promptId: string): Promise<void>
+```
+
+- **`promptId`**: Unique prompt identifier
+
+**Returns:** `void` (204 No Content on success)
+
+##### Aliases
+
+```typescript
+fetch(promptId, version?) // Alias for get()
+save(promptId, input)     // Alias for put()
+```
+
+## TypeScript Types
+
+```typescript
+interface PromptEnvelope {
+  id: string;
+  content: string;
+  meta: {
+    version?: string;
+    author?: string;
+    description?: string;
+    model_config?: Record<string, any>;
+    [key: string]: any;
+  };
+}
+
+interface PromptInput {
+  content: string;
+  meta?: Record<string, any>;
+}
+```
+
+## Error Handling
+
+```typescript
+import { PLPClient, PLPError } from '@plp/client';
+
+try {
+  const prompt = await client.get('missing/prompt');
+} catch (error) {
+  if (error instanceof PLPError) {
+    console.error('Status:', error.statusCode);
+    console.error('Message:', error.message);
+  }
+}
+```
+
+## Examples
+
+### Using with OpenAI
+
+```typescript
+import { PLPClient } from '@plp/client';
+import OpenAI from 'openai';
+
+const plp = new PLPClient('https://prompts.goreal.ai');
+const openai = new OpenAI();
+
+const prompt = await plp.get('assistant/code-reviewer');
+
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: prompt.content }],
+  temperature: prompt.meta.model_config?.temperature || 0.7
+});
+```
+
+### Using with Anthropic
+
+```typescript
+import { PLPClient } from '@plp/client';
+import Anthropic from '@anthropic-ai/sdk';
+
+const plp = new PLPClient('https://prompts.goreal.ai');
+const anthropic = new Anthropic();
+
+const prompt = await plp.get('creative/story-generator');
+
+const message = await anthropic.messages.create({
+  model: 'claude-3-opus-20240229',
+  max_tokens: prompt.meta.model_config?.max_tokens || 1024,
+  messages: [{ role: 'user', content: prompt.content }]
+});
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Test
+npm test
+
+# Lint
+npm run lint
+```
+
+## License
+
+MIT © [GoReal.AI](https://goreal.ai)
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md)
+
+## Learn More
+
+- [PLP Specification](../../spec/SPEC.md)
+- [OpenAPI Documentation](../../spec/openapi.yaml)
+- [GitHub Repository](https://github.com/gorealai/plp)

package/dist/index.d.mts

@@ -0,0 +1,67 @@
+/**
+ * plp-client - Official JavaScript/TypeScript client for PLP (Prompt Library Protocol)
+ * @license MIT
+ */
+interface PromptEnvelope {
+    id: string;
+    content: string;
+    meta: {
+        version?: string;
+        author?: string;
+        description?: string;
+        model_config?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+}
+interface PromptInput {
+    content: string;
+    meta?: Record<string, unknown>;
+}
+interface PLPClientOptions {
+    apiKey?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+declare class PLPError extends Error {
+    statusCode?: number | undefined;
+    response?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
+}
+declare class PLPClient {
+    private baseUrl;
+    private apiKey?;
+    private headers;
+    private timeout;
+    constructor(baseUrl: string, options?: PLPClientOptions);
+    private request;
+    /**
+     * Retrieve a prompt by ID and optional version
+     * @param promptId - The unique prompt identifier
+     * @param version - Optional version string (e.g., "1.2.0"). If omitted, returns latest.
+     * @returns The prompt envelope
+     */
+    get(promptId: string, version?: string): Promise<PromptEnvelope>;
+    /**
+     * Create or update a prompt (idempotent upsert)
+     * @param promptId - The unique prompt identifier
+     * @param input - The prompt content and metadata
+     * @returns The saved prompt envelope
+     */
+    put(promptId: string, input: PromptInput): Promise<PromptEnvelope>;
+    /**
+     * Delete a prompt and all its versions
+     * @param promptId - The unique prompt identifier
+     * @returns void (204 No Content on success)
+     */
+    delete(promptId: string): Promise<void>;
+    /**
+     * Alias for get() - more intuitive naming
+     */
+    fetch(promptId: string, version?: string): Promise<PromptEnvelope>;
+    /**
+     * Alias for put() - more intuitive naming
+     */
+    save(promptId: string, input: PromptInput): Promise<PromptEnvelope>;
+}
+
+export { PLPClient, type PLPClientOptions, PLPError, type PromptEnvelope, type PromptInput, PLPClient as default };

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * plp-client - Official JavaScript/TypeScript client for PLP (Prompt Library Protocol)
+ * @license MIT
+ */
+interface PromptEnvelope {
+    id: string;
+    content: string;
+    meta: {
+        version?: string;
+        author?: string;
+        description?: string;
+        model_config?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+}
+interface PromptInput {
+    content: string;
+    meta?: Record<string, unknown>;
+}
+interface PLPClientOptions {
+    apiKey?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+declare class PLPError extends Error {
+    statusCode?: number | undefined;
+    response?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
+}
+declare class PLPClient {
+    private baseUrl;
+    private apiKey?;
+    private headers;
+    private timeout;
+    constructor(baseUrl: string, options?: PLPClientOptions);
+    private request;
+    /**
+     * Retrieve a prompt by ID and optional version
+     * @param promptId - The unique prompt identifier
+     * @param version - Optional version string (e.g., "1.2.0"). If omitted, returns latest.
+     * @returns The prompt envelope
+     */
+    get(promptId: string, version?: string): Promise<PromptEnvelope>;
+    /**
+     * Create or update a prompt (idempotent upsert)
+     * @param promptId - The unique prompt identifier
+     * @param input - The prompt content and metadata
+     * @returns The saved prompt envelope
+     */
+    put(promptId: string, input: PromptInput): Promise<PromptEnvelope>;
+    /**
+     * Delete a prompt and all its versions
+     * @param promptId - The unique prompt identifier
+     * @returns void (204 No Content on success)
+     */
+    delete(promptId: string): Promise<void>;
+    /**
+     * Alias for get() - more intuitive naming
+     */
+    fetch(promptId: string, version?: string): Promise<PromptEnvelope>;
+    /**
+     * Alias for put() - more intuitive naming
+     */
+    save(promptId: string, input: PromptInput): Promise<PromptEnvelope>;
+}
+
+export { PLPClient, type PLPClientOptions, PLPError, type PromptEnvelope, type PromptInput, PLPClient as default };

package/dist/index.js

@@ -0,0 +1,140 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PLPClient: () => PLPClient,
+  PLPError: () => PLPError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var PLPError = class extends Error {
+  constructor(message, statusCode, response) {
+    super(message);
+    this.statusCode = statusCode;
+    this.response = response;
+    this.name = "PLPError";
+  }
+};
+var PLPClient = class {
+  constructor(baseUrl, options = {}) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.apiKey = options.apiKey;
+    this.headers = options.headers || {};
+    this.timeout = options.timeout || 1e4;
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.headers
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (response.status === 204) {
+        return void 0;
+      }
+      const data = await response.json();
+      if (!response.ok) {
+        const errorData = data;
+        throw new PLPError(
+          errorData.error || `HTTP ${response.status}`,
+          response.status,
+          data
+        );
+      }
+      return data;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof PLPError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new PLPError(`Request timeout after ${this.timeout}ms`);
+        }
+        throw new PLPError(`Network error: ${error.message}`);
+      }
+      throw new PLPError("Unknown error occurred");
+    }
+  }
+  /**
+   * Retrieve a prompt by ID and optional version
+   * @param promptId - The unique prompt identifier
+   * @param version - Optional version string (e.g., "1.2.0"). If omitted, returns latest.
+   * @returns The prompt envelope
+   */
+  async get(promptId, version) {
+    const path = version ? `/v1/prompts/${promptId}/${version}` : `/v1/prompts/${promptId}`;
+    return this.request("GET", path);
+  }
+  /**
+   * Create or update a prompt (idempotent upsert)
+   * @param promptId - The unique prompt identifier
+   * @param input - The prompt content and metadata
+   * @returns The saved prompt envelope
+   */
+  async put(promptId, input) {
+    const path = `/v1/prompts/${promptId}`;
+    return this.request("PUT", path, input);
+  }
+  /**
+   * Delete a prompt and all its versions
+   * @param promptId - The unique prompt identifier
+   * @returns void (204 No Content on success)
+   */
+  async delete(promptId) {
+    const path = `/v1/prompts/${promptId}`;
+    return this.request("DELETE", path);
+  }
+  /**
+   * Alias for get() - more intuitive naming
+   */
+  async fetch(promptId, version) {
+    return this.get(promptId, version);
+  }
+  /**
+   * Alias for put() - more intuitive naming
+   */
+  async save(promptId, input) {
+    return this.put(promptId, input);
+  }
+};
+var index_default = PLPClient;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PLPClient,
+  PLPError
+});
+/**
+ * plp-client - Official JavaScript/TypeScript client for PLP (Prompt Library Protocol)
+ * @license MIT
+ */

package/dist/index.mjs

@@ -0,0 +1,114 @@
+// src/index.ts
+var PLPError = class extends Error {
+  constructor(message, statusCode, response) {
+    super(message);
+    this.statusCode = statusCode;
+    this.response = response;
+    this.name = "PLPError";
+  }
+};
+var PLPClient = class {
+  constructor(baseUrl, options = {}) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.apiKey = options.apiKey;
+    this.headers = options.headers || {};
+    this.timeout = options.timeout || 1e4;
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Content-Type": "application/json",
+      ...this.headers
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (response.status === 204) {
+        return void 0;
+      }
+      const data = await response.json();
+      if (!response.ok) {
+        const errorData = data;
+        throw new PLPError(
+          errorData.error || `HTTP ${response.status}`,
+          response.status,
+          data
+        );
+      }
+      return data;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof PLPError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new PLPError(`Request timeout after ${this.timeout}ms`);
+        }
+        throw new PLPError(`Network error: ${error.message}`);
+      }
+      throw new PLPError("Unknown error occurred");
+    }
+  }
+  /**
+   * Retrieve a prompt by ID and optional version
+   * @param promptId - The unique prompt identifier
+   * @param version - Optional version string (e.g., "1.2.0"). If omitted, returns latest.
+   * @returns The prompt envelope
+   */
+  async get(promptId, version) {
+    const path = version ? `/v1/prompts/${promptId}/${version}` : `/v1/prompts/${promptId}`;
+    return this.request("GET", path);
+  }
+  /**
+   * Create or update a prompt (idempotent upsert)
+   * @param promptId - The unique prompt identifier
+   * @param input - The prompt content and metadata
+   * @returns The saved prompt envelope
+   */
+  async put(promptId, input) {
+    const path = `/v1/prompts/${promptId}`;
+    return this.request("PUT", path, input);
+  }
+  /**
+   * Delete a prompt and all its versions
+   * @param promptId - The unique prompt identifier
+   * @returns void (204 No Content on success)
+   */
+  async delete(promptId) {
+    const path = `/v1/prompts/${promptId}`;
+    return this.request("DELETE", path);
+  }
+  /**
+   * Alias for get() - more intuitive naming
+   */
+  async fetch(promptId, version) {
+    return this.get(promptId, version);
+  }
+  /**
+   * Alias for put() - more intuitive naming
+   */
+  async save(promptId, input) {
+    return this.put(promptId, input);
+  }
+};
+var index_default = PLPClient;
+export {
+  PLPClient,
+  PLPError,
+  index_default as default
+};
+/**
+ * plp-client - Official JavaScript/TypeScript client for PLP (Prompt Library Protocol)
+ * @license MIT
+ */

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "plp-client",
+  "version": "1.0.0",
+  "description": "Official JavaScript/TypeScript client for PLP (Prompt Library Protocol)",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "plp",
+    "prompt",
+    "library",
+    "protocol",
+    "ai",
+    "llm",
+    "openai",
+    "anthropic",
+    "prompt-management"
+  ],
+  "author": "GoReal.AI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gorealai/plp.git",
+    "directory": "sdks/js"
+  },
+  "bugs": {
+    "url": "https://github.com/gorealai/plp/issues"
+  },
+  "homepage": "https://github.com/gorealai/plp#readme",
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0",
+    "eslint": "^8.54.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.0.4"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}