@privateconnect/sdk 0.7.5 → 0.8.6

package/README.md

@@ -1,174 +1,192 @@
-# Private Connect SDK
-
-TypeScript SDK for Private Connect - programmatic access to services and agent orchestration.
-
-## Installation
-
-```bash
-npm install @privateconnect/sdk
-# or
-pnpm add @privateconnect/sdk
-```
-
-## Quick Start
-
-```typescript
-import { PrivateConnect, connect } from '@privateconnect/sdk';
-
-// Quick connect to a service
-const db = await connect('postgres-prod');
-console.log(db.connectionString); // postgres://localhost:5432/...
-
-// Or use the full client
-const pc = new PrivateConnect({ 
-  apiKey: process.env.PRIVATECONNECT_API_KEY 
-});
-
-// List available services
-const services = await pc.services.list();
-
-// Connect to a specific service
-const redis = await pc.connect('redis-cache');
-console.log(redis.connectionString); // redis://localhost:6379
-```
-
-## Agent Orchestration
-
-The SDK enables multi-agent orchestration - coordinating work across agents running on different machines.
-
-### List Agents
-
-```typescript
-// Get all agents in your workspace
-const agents = await pc.agents.list();
-
-// Get only online agents
-const online = await pc.agents.list({ onlineOnly: true });
-
-// Find agents with specific capabilities
-const gpuAgents = await pc.agents.findByCapability('gpu');
-```
-
-### Register Capabilities
-
-Tell other agents what you can do:
-
-```typescript
-await pc.agents.registerCapabilities([
-  { name: 'database', metadata: { type: 'postgres', version: '15' } },
-  { name: 'gpu', metadata: { model: 'A100', memory: '80GB' } },
-]);
-```
-
-### Agent Messaging
-
-Coordinate with other agents:
-
-```typescript
-// Send a message to a specific agent
-await pc.agents.sendMessage(targetAgentId, {
-  action: 'run-migration',
-  database: 'users',
-});
-
-// Broadcast to all agents
-await pc.agents.broadcast({
-  type: 'deployment-starting',
-  service: 'api',
-});
-
-// Get your messages
-const messages = await pc.agents.getMessages({ unreadOnly: true });
-for (const msg of messages) {
-  console.log(`From ${msg.from.name}: ${JSON.stringify(msg.payload)}`);
-}
-```
-
-### Orchestration Sessions
-
-Create ephemeral sessions for coordinated workflows:
-
-```typescript
-// Create a session
-const session = await pc.sessions.create('deploy-v2.1', {
-  ttlMinutes: 30,
-  metadata: { version: '2.1.0' },
-});
-
-// ... coordinate agents ...
-
-// End the session
-await pc.sessions.end(session.id);
-```
-
-## Connection Strings
-
-Get properly formatted connection strings for common services:
-
-```typescript
-const db = await pc.connect('postgres-prod');
-// db.connectionString = 'postgres://localhost:5432/postgres'
-// db.envVar = 'DATABASE_URL'
-
-const cache = await pc.connect('redis-cache');
-// cache.connectionString = 'redis://localhost:6379'
-// cache.envVar = 'REDIS_URL'
-
-const api = await pc.connect('internal-api');
-// api.connectionString = 'http://localhost:8080'
-// api.envVar = 'API_URL'
-```
-
-## Environment Variables
-
-The SDK can read configuration from environment variables:
-
-```bash
-export PRIVATECONNECT_API_KEY=your-api-key
-```
-
-```typescript
-// API key automatically read from env
-const connection = await connect('my-service');
-```
-
-## API Reference
-
-### `PrivateConnect`
-
-Main client class.
-
-```typescript
-const pc = new PrivateConnect({
-  apiKey: string,        // Required: Your API key
-  hubUrl?: string,       // Optional: Hub URL (default: https://api.privateconnect.co)
-  agentId?: string,      // Optional: Agent ID (auto-detected)
-});
-```
-
-### `pc.services`
-
-- `list()` - List all services
-- `get(name)` - Get a service by name
-- `getConnection(name)` - Get connection details for a service
-
-### `pc.agents`
-
-- `list(options?)` - List all agents
-- `findByCapability(capability)` - Find agents by capability
-- `registerCapabilities(capabilities)` - Register this agent's capabilities
-- `sendMessage(toAgentId, payload, options?)` - Send a message
-- `broadcast(payload, options?)` - Broadcast to all agents
-- `getMessages(options?)` - Get received messages
-- `markRead(messageIds)` - Mark messages as read
-
-### `pc.sessions`
-
-- `create(name, options?)` - Create an orchestration session
-- `end(sessionId)` - End a session
-- `getActive()` - Get active sessions
-
-## License
-
-[FSL-1.1-MIT](LICENSE)
-
+# Private Connect SDK
+
+Define your connections in `pconnect.yml`. Access them from anywhere — your app, CI, an AI agent.
+
+## Install
+
+```bash
+npm install @privateconnect/sdk
+```
+
+## Quick Start
+
+**1. Create `pconnect.yml` in your project root:**
+
+```yaml
+resources:
+  staging-db:
+    type: postgres
+    host: internal-db
+    port: 5432
+    access:
+      mode: tcp
+  redis-cache:
+    type: redis
+    host: redis.internal
+    port: 6379
+    access:
+      mode: tcp
+```
+
+**2. Use it in your code:**
+
+```typescript
+import { PrivateConnect } from '@privateconnect/sdk';
+
+const pc = PrivateConnect.fromManifest();
+
+const db = pc.resource('staging-db');
+console.log(db.connectionString); // postgres://internal-db:5432
+console.log(db.envVar);           // DATABASE_URL
+
+const cache = pc.resource('redis-cache');
+console.log(cache.connectionString); // redis://redis.internal:6379
+```
+
+**3. Run `connect dev` to make it live:**
+
+```bash
+connect dev
+# → Provisions tunnels for every resource in pconnect.yml
+# → Your app's connection strings now resolve to live services
+```
+
+That's it. Your app declares what it connects to. `connect dev` makes it work. An AI agent (or a teammate) can modify `pconnect.yml` to change the topology — without touching application code.
+
+## Why This Matters
+
+The `pconnect.yml` file is a diffable, reviewable, mergeable description of your project's connectivity. When an AI modifies it — adding a read replica, changing a TTL, switching an access mode — that's a PR you can review and merge. The SDK reads the manifest; the agent provisions it.
+
+## Manifest API
+
+### `PrivateConnect.fromManifest(path?, config?)`
+
+Load a manifest and return a configured client. Auto-discovers `pconnect.yml` in the current directory (or parents) if no path is given.
+
+```typescript
+// Auto-discover
+const pc = PrivateConnect.fromManifest();
+
+// Explicit path
+const pc = PrivateConnect.fromManifest('./infra/pconnect.yml');
+
+// With hub API access (for grants, orchestration, etc.)
+const pc = PrivateConnect.fromManifest('./pconnect.yml', {
+  apiKey: process.env.PRIVATECONNECT_API_KEY,
+});
+```
+
+### `pc.resource(name)`
+
+Get a resource by name. Returns its resolved type, host, port, connection string, and suggested environment variable.
+
+```typescript
+const db = pc.resource('staging-db');
+// {
+//   name: 'staging-db',
+//   type: 'postgres',
+//   host: 'internal-db',
+//   port: 5432,
+//   connectionString: 'postgres://internal-db:5432',
+//   envVar: 'DATABASE_URL',
+//   accessMode: 'tcp',
+//   via: 'direct'
+// }
+```
+
+### `pc.resources()`
+
+List all resources declared in the manifest.
+
+```typescript
+const all = pc.resources();
+all.forEach(r => console.log(`${r.name}: ${r.connectionString}`));
+```
+
+### `pc.envBlock()`
+
+Generate a `.env`-compatible block for all resources.
+
+```typescript
+console.log(pc.envBlock());
+// DATABASE_URL=postgres://internal-db:5432
+// REDIS_URL=redis://redis.internal:6379
+// API_URL=http://payments.service.internal:3000
+```
+
+## Hub API
+
+When you pass an API key, you also get access to the hub APIs for grants, agents, and services.
+
+### Grants
+
+Grant an AI agent temporary, scoped access to a private resource.
+
+```typescript
+const pc = PrivateConnect.fromManifest('./pconnect.yml', {
+  apiKey: process.env.PRIVATECONNECT_API_KEY,
+});
+
+const grant = await pc.grants.create({
+  agentLabel: 'claude',
+  resourceType: 'db',
+  resourceName: 'postgres',
+  ttl: '5m',
+});
+console.log(grant.token); // gnt_...
+```
+
+### Agent Orchestration
+
+Coordinate agents across machines.
+
+```typescript
+const agents = await pc.agents.list({ onlineOnly: true });
+const gpuAgents = await pc.agents.findByCapability('gpu');
+
+await pc.agents.sendMessage(gpuAgents[0].id, {
+  action: 'run-training',
+  dataset: 'v2',
+});
+```
+
+### Services
+
+Query hub-registered services directly.
+
+```typescript
+const services = await pc.services.list();
+const conn = await pc.connect('prod-db');
+console.log(conn.connectionString);
+```
+
+## Manifest Format
+
+The `pconnect.yml` file supports the following resource types:
+
+| Type | Default Port | Connection String | Env Var |
+|------|-------------|-------------------|---------|
+| `postgres` | 5432 | `postgres://host:port` | `DATABASE_URL` |
+| `mysql` | 3306 | `mysql://host:port` | `DATABASE_URL` |
+| `redis` | 6379 | `redis://host:port` | `REDIS_URL` |
+| `http` | 80 | `http://host:port` | `API_URL` |
+| `generic-tcp` | — | `tcp://host:port` | `<NAME>_URL` |
+
+Access modes:
+- `tcp` — direct TCP tunnel (databases, Redis, generic)
+- `http` — HTTP-level proxying
+
+Transport:
+- `direct` (default) — connect directly to the target
+- `hub` — route through the Private Connect hub when the target isn't directly reachable
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `PRIVATECONNECT_API_KEY` | API key for hub access (grants, orchestration) |
+| `CONNECT_HUB_URL` | Hub URL (default: `https://api.privateconnect.co`) |
+
+## License
+
+[FSL-1.1-MIT](LICENSE)

package/dist/index.d.ts

@@ -1,34 +1,35 @@
 /**
  * Private Connect SDK
  *
- * Programmatic access to Private Connect services, grants, and agent orchestration.
+ * Define your connections in pconnect.yml. Access them from anywhere.
  *
  * @example
  * ```typescript
  * import { PrivateConnect } from '@privateconnect/sdk';
  *
- * const pc = new PrivateConnect({ apiKey: 'your-api-key' });
+ * // Load your project's connection manifest
+ * const pc = PrivateConnect.fromManifest();
  *
- * // Connect to a service (assumes tunnel is already open)
- * const db = await pc.connect('postgres-prod');
- * console.log(db.connectionString); // postgres://localhost:5432/...
+ * // Get a resource declared in pconnect.yml
+ * const db = pc.resource('staging-db');
+ * console.log(db.connectionString); // postgres://internal-db:5432
+ * console.log(db.envVar);           // DATABASE_URL
  *
- * // Grant an AI agent temporary access
- * const grant = await pc.grants.create({
+ * // With an API key, you also get hub API access
+ * const pc2 = PrivateConnect.fromManifest('./pconnect.yml', {
+ *   apiKey: process.env.PRIVATECONNECT_API_KEY,
+ * });
+ * const grant = await pc2.grants.create({
  *   agentLabel: 'claude',
  *   resourceType: 'db',
  *   resourceName: 'postgres',
  *   ttl: '5m',
  * });
- * console.log(grant.token); // gnt_...
- *
- * // List all agents
- * const agents = await pc.agents.list();
  * ```
  */
 export interface PrivateConnectConfig {
-    /** API key for authentication */
-    apiKey: string;
+    /** API key for authentication. Required for hub API calls; optional for manifest-only usage. */
+    apiKey?: string;
     /** Hub URL (default: https://api.privateconnect.co) */
     hubUrl?: string;
     /** Agent ID (auto-detected from local config if not provided) */
@@ -95,14 +96,109 @@ export interface Grant {
 export interface GrantCreateOptions {
     agentLabel: string;
     resourceType: 'db' | 'api' | 'path';
-    resourceName: string;
+    resourceName?: string;
+    groupId?: string;
     scope?: 'read-only' | 'full';
     /** Duration string: 60s, 5m, 1h, 1d. Omit for persistent grant. */
     ttl?: string;
 }
+export interface ServiceRegisterOptions {
+    agentId: string;
+    name: string;
+    targetHost: string;
+    targetPort: number;
+    protocol?: 'auto' | 'tcp' | 'udp' | 'http' | 'https';
+    isPublic?: boolean;
+    groupId?: string;
+}
+export interface ProvisionOptions {
+    clientType: string;
+    label?: string;
+    name?: string;
+    ttlSeconds?: number;
+}
+export interface ProvisionResult {
+    agentId: string;
+    token: string;
+    expiresAt: string;
+    workspaceId: string;
+    workspaceName: string;
+}
+export interface ShareCreateOptions {
+    name: string;
+    description?: string;
+    expiresIn?: '1h' | '24h' | '7d' | '30d' | 'never';
+    allowedPaths?: string[];
+    allowedMethods?: ('GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE')[];
+    rateLimitPerMin?: number;
+}
+export interface Share {
+    id: string;
+    name: string;
+    description?: string;
+    expiresAt: string | null;
+    revokedAt: string | null;
+    createdAt: string;
+    isActive: boolean;
+    shareUrl: string;
+    tokenPreview: string;
+}
+export interface ServiceGroup {
+    id: string;
+    name: string;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+    services: Array<{
+        id: string;
+        name: string;
+        status: string;
+        protocol: string;
+    }>;
+}
+export interface GroupCreateOptions {
+    name: string;
+    metadata?: Record<string, unknown>;
+    services?: Array<{
+        agentId: string;
+        name: string;
+        targetHost: string;
+        targetPort: number;
+        protocol?: string;
+        isPublic?: boolean;
+    }>;
+}
+export declare const RESOURCE_TYPES: readonly ["postgres", "mysql", "redis", "http", "generic-tcp"];
+export type ResourceType = typeof RESOURCE_TYPES[number];
+export declare const ACCESS_MODES: readonly ["tcp", "http"];
+export type AccessMode = typeof ACCESS_MODES[number];
+export declare const TRANSPORT_MODES: readonly ["direct", "hub"];
+export type TransportVia = typeof TRANSPORT_MODES[number];
+export interface ManifestResourceConfig {
+    type: ResourceType;
+    host?: string;
+    port?: number;
+    targetHost?: string;
+    targetPort?: number;
+    url?: string;
+    access: {
+        mode: AccessMode;
+        via?: TransportVia;
+    };
+}
+export interface ManifestResource {
+    name: string;
+    type: ResourceType;
+    host: string;
+    port: number;
+    connectionString: string;
+    envVar: string;
+    accessMode: AccessMode;
+    via: TransportVia;
+}
 export declare class AgentsAPI {
     private client;
     constructor(client: PrivateConnect);
+    provision(options: ProvisionOptions): Promise<ProvisionResult>;
     list(options?: {
         onlineOnly?: boolean;
     }): Promise<Agent[]>;
@@ -132,8 +228,13 @@ export declare class AgentsAPI {
 export declare class ServicesAPI {
     private client;
     constructor(client: PrivateConnect);
+    register(options: ServiceRegisterOptions): Promise<Service>;
     list(): Promise<Service[]>;
     get(name: string): Promise<Service | null>;
+    update(id: string, options: {
+        name?: string;
+    }): Promise<void>;
+    delete(id: string): Promise<void>;
     /**
      * Get connection details for a service.
      *
@@ -168,15 +269,92 @@ export declare class GrantsAPI {
      */
     validate(token: string): Promise<Grant | null>;
 }
+export declare class SharesAPI {
+    private client;
+    constructor(client: PrivateConnect);
+    create(serviceId: string, options: ShareCreateOptions): Promise<{
+        id: string;
+        token: string;
+        shareUrl: string;
+        expiresAt: string | null;
+    }>;
+    list(serviceId: string): Promise<Share[]>;
+    revoke(shareId: string): Promise<void>;
+}
+export declare class GroupsAPI {
+    private client;
+    constructor(client: PrivateConnect);
+    create(options: GroupCreateOptions): Promise<ServiceGroup>;
+    list(): Promise<ServiceGroup[]>;
+    get(id: string): Promise<ServiceGroup>;
+    addService(groupId: string, options: Omit<ServiceRegisterOptions, 'groupId'>): Promise<Service>;
+    createShares(groupId: string, options: {
+        name: string;
+        description?: string;
+        expiresIn?: string;
+    }): Promise<Array<{
+        id: string;
+        token: string;
+        serviceName: string;
+        shareUrl: string;
+    }>>;
+    delete(id: string): Promise<{
+        deletedServices: number;
+    }>;
+}
 export declare class PrivateConnect {
     private config;
-    /** Agents API for discovery and orchestration */
+    private manifest;
+    private manifestPath?;
+    /** Agents API for discovery, orchestration, and provisioning */
     agents: AgentsAPI;
-    /** Services API for connecting to services */
+    /** Services API for registering, connecting to, and managing services */
     services: ServicesAPI;
     /** Grants API for managing scoped access tokens (time-limited or persistent) */
     grants: GrantsAPI;
-    constructor(config: PrivateConnectConfig);
+    /** Shares API for creating and managing service share links */
+    shares: SharesAPI;
+    /** Groups API for managing service groups (per-branch, per-project environments) */
+    groups: GroupsAPI;
+    constructor(config?: PrivateConnectConfig);
+    /**
+     * Load a pconnect.yml manifest and return a configured client.
+     *
+     * Auto-discovers pconnect.yml in the current directory (or parents) if no
+     * path is given. Pass a config to also enable hub API access.
+     *
+     * @example
+     * ```typescript
+     * const pc = PrivateConnect.fromManifest();
+     * const db = pc.resource('staging-db');
+     * console.log(db.connectionString); // postgres://internal-db:5432
+     * ```
+     */
+    static fromManifest(manifestPath?: string, config?: PrivateConnectConfig): PrivateConnect;
+    /**
+     * Get a resource declared in pconnect.yml by name.
+     *
+     * Returns its type, host, port, connection string, and suggested env var.
+     * When `connect dev` is running, the connection string points to a live
+     * local tunnel.
+     */
+    resource(name: string): ManifestResource;
+    /**
+     * List all resources declared in the loaded manifest.
+     */
+    resources(): ManifestResource[];
+    /**
+     * Generate a `.env`-compatible block for all manifest resources.
+     *
+     * @example
+     * ```typescript
+     * const pc = PrivateConnect.fromManifest();
+     * console.log(pc.envBlock());
+     * // DATABASE_URL=postgres://internal-db:5432
+     * // REDIS_URL=redis://redis.internal:6379
+     * ```
+     */
+    envBlock(): string;
     /** The resolved agent ID, or undefined if not configured. */
     get agentId(): string | undefined;
     /** The hub URL this client is connected to. */
@@ -193,11 +371,18 @@ export declare class PrivateConnect {
      * Used by APIs that require an authenticated agent identity.
      */
     requireAgentId(): string;
+    /** Requires an API key or throws. */
+    private requireApiKey;
     /** Internal fetch with API key auth. */
-    fetch(path: string, options?: RequestInit): Promise<Response>;
+    fetch(urlPath: string, options?: RequestInit): Promise<Response>;
 }
 export default PrivateConnect;
-/** Convenience function for quick one-off connections. */
+/** Convenience function for quick one-off connections via the hub API. */
 export declare function connect(serviceName: string, config?: PrivateConnectConfig & {
     grantToken?: string;
 }): Promise<Connection>;
+/**
+ * Load pconnect.yml and get a resource by name.
+ * Shorthand for `PrivateConnect.fromManifest().resource(name)`.
+ */
+export declare function fromManifest(manifestPath?: string): PrivateConnect;