@sylphx/sdk 0.4.0 → 0.5.0

package/dist/server/index.d.cts

@@ -19559,6 +19559,129 @@ declare function createRestClient(config: RestClientConfig): openapi_fetch.Clien
  */
 type RestClient = ReturnType<typeof createRestClient>;
 
+declare class InvalidConnectionUrlError extends Error {
+    readonly code: "INVALID_CONNECTION_URL";
+    constructor(message: string);
+}
+
+/**
+ * SDK Configuration — ADR-055 Connection URL API
+ *
+ * v0.5.0: The primary entry point is `createClient(url)` which accepts
+ * a `sylphx://` connection URL. The old `createConfig({ ref, publicKey })`
+ * API is removed.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@sylphx/sdk'
+ *
+ * const sylphx = createClient(process.env.SYLPHX_URL!)
+ * // Parses: sylphx://pk_prod_{hex}@bold-river-a1b2c3.sylphx.com
+ * ```
+ */
+
+/**
+ * SDK Configuration object — immutable, frozen.
+ *
+ * Created by `createClient()` or `createServerClient()`.
+ * Passed to all pure SDK functions (`track()`, `signIn()`, etc.).
+ */
+interface SylphxConfig {
+    /** The credential string (pk_* or sk_*) */
+    readonly credential: string;
+    /** Credential type: 'pk' (publishable) or 'sk' (secret) */
+    readonly credentialType: 'pk' | 'sk';
+    /** Target environment: dev, stg, prod, or prev */
+    readonly env: 'dev' | 'stg' | 'prod' | 'prev';
+    /** Resource slug (first DNS label), e.g. 'bold-river-a1b2c3' */
+    readonly slug: string;
+    /** Pre-computed API base URL, e.g. 'https://bold-river-a1b2c3.sylphx.com/v1' */
+    readonly baseUrl: string;
+    /** Optional access token for authenticated requests */
+    readonly accessToken?: string;
+    /**
+     * Secret key — populated when credentialType is 'sk'.
+     * Backward-compatible alias for `credential` when credential is sk_*.
+     */
+    readonly secretKey?: string;
+    /**
+     * Publishable key — populated when credentialType is 'pk'.
+     * Backward-compatible alias for `credential` when credential is pk_*.
+     */
+    readonly publicKey?: string;
+    /**
+     * @deprecated Use `slug`. Backward-compatible alias.
+     */
+    readonly ref: string;
+}
+/**
+ * Explicit components input — alternative to connection URL string.
+ *
+ * For multi-tenant apps or cases where components are stored separately.
+ */
+interface SylphxClientInput {
+    /** Resource slug, e.g. 'bold-river-a1b2c3' */
+    slug?: string;
+    /** Publishable key (pk_*) — client-safe */
+    publicKey?: string;
+    /** Secret key (sk_*) — server-side only */
+    secretKey?: string;
+    /** Optional access token */
+    accessToken?: string;
+    /** API domain override (default: sylphx.com) */
+    domain?: string;
+    /**
+     * @deprecated Use `slug`. Accepted for backward compatibility during migration.
+     */
+    ref?: string;
+    /**
+     * @deprecated Use `domain`. Accepted for backward compatibility during migration.
+     */
+    platformUrl?: string;
+}
+/**
+ * Create a Sylphx client from a connection URL or explicit components.
+ *
+ * This is the primary SDK entry point for client-side (browser) usage.
+ * Accepts a `sylphx://` connection URL or an explicit components object.
+ *
+ * @example Connection URL (recommended)
+ * ```typescript
+ * const sylphx = createClient(process.env.NEXT_PUBLIC_SYLPHX_URL!)
+ * // Parses: sylphx://pk_prod_{hex}@bold-river-a1b2c3.sylphx.com
+ * ```
+ *
+ * @example Explicit components
+ * ```typescript
+ * const sylphx = createClient({
+ *   slug: 'bold-river-a1b2c3',
+ *   publicKey: 'pk_prod_f19e...',
+ * })
+ * ```
+ */
+declare function createClient(input: string | SylphxClientInput): SylphxConfig;
+/**
+ * Create a Sylphx server client from a connection URL or explicit components.
+ *
+ * Equivalent to `createClient()` but validates that a secret key (sk_*) is provided.
+ * Use this for server-side operations that require elevated permissions.
+ *
+ * @example Connection URL (recommended)
+ * ```typescript
+ * const sylphx = createServerClient(process.env.SYLPHX_SECRET_URL!)
+ * // Parses: sylphx://sk_prod_{hex}@bold-river-a1b2c3.sylphx.com
+ * ```
+ *
+ * @example Explicit components
+ * ```typescript
+ * const sylphx = createServerClient({
+ *   slug: 'bold-river-a1b2c3',
+ *   secretKey: 'sk_prod_5120...',
+ * })
+ * ```
+ */
+declare function createServerClient(input: string | SylphxClientInput): SylphxConfig;
+
 /**
  * Consent Functions
  *
@@ -19934,6 +20057,227 @@ declare function validateAndSanitizeKey(key: string | undefined | null): string;
  */
 declare function isDevelopmentRuntime(): boolean;
 
+/**
+ * Functions Client — Serverless V8 Isolate Functions (ADR-043)
+ *
+ * Deploy and manage serverless functions powered by Supabase Edge Runtime.
+ * Functions run in isolated V8 contexts with < 5ms cold starts.
+ *
+ * ## Key Concepts
+ *
+ * - Functions are TypeScript/JavaScript handlers deployed to the Sylphx edge runtime
+ * - Invoked via HTTP: GET/POST https://{project}.sylphx.app/functions/{name}
+ * - Can access all Sylphx BaaS services via the SDK inside the handler
+ * - Isolated per project — no shared state between projects
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * // functions/hello-world/index.ts — your function code
+ * import { createServerClient } from '@sylphx/sdk/server'
+ *
+ * export default async function handler(req: Request): Promise<Response> {
+ *   const { name } = await req.json()
+ *   return Response.json({ message: `Hello, ${name}!` })
+ * }
+ * ```
+ *
+ * ```bash
+ * # Deploy via CLI
+ * sylphx functions deploy hello-world
+ * # → https://my-project.sylphx.app/functions/hello-world
+ * ```
+ *
+ * ```typescript
+ * // Or deploy programmatically via SDK
+ * import { createConfig, FunctionsClient } from '@sylphx/sdk'
+ *
+ * const config = createConfig({ secretKey: process.env.SYLPHX_SECRET_KEY! })
+ *
+ * await FunctionsClient.deploy(config, {
+ *   name: 'hello-world',
+ *   code: `export default async (req) => Response.json({ ok: true })`,
+ * })
+ *
+ * // Invoke the function
+ * const result = await FunctionsClient.invoke(config, 'hello-world', { name: 'world' })
+ * ```
+ *
+ * ## Available in handler
+ *
+ * All Web Standard APIs are available inside function handlers:
+ * - `fetch()` — HTTP requests
+ * - `Request`, `Response`, `Headers`, `URL`
+ * - `crypto` — Web Crypto API
+ * - `TextEncoder`, `TextDecoder`
+ * - `Deno.env.get('KEY')` — access injected env vars
+ *
+ * ## Constraints
+ *
+ * - Memory: 150 MB default (max 512 MB)
+ * - Timeout: 30s default (max 120s)
+ * - No filesystem access (`fs` module unavailable)
+ * - No raw socket access (`net` module unavailable)
+ * - npm packages via CDN URL: `import { z } from 'https://esm.sh/zod'`
+ */
+
+type FunctionStatus = 'active' | 'deploying' | 'failed' | 'disabled';
+type FunctionRuntime = 'deno';
+interface FunctionDeployOptions {
+    /**
+     * Function slug — URL-safe name (lowercase kebab-case).
+     * Used in the invocation URL: /functions/{name}
+     */
+    name: string;
+    /**
+     * TypeScript/JavaScript source code.
+     * Must export a default handler function:
+     *   export default async function(req: Request): Promise<Response> { ... }
+     *
+     * For functions > 100KB, use the CLI: sylphx functions deploy
+     */
+    code: string;
+    /** Human-readable display name */
+    displayName?: string;
+    /** Short description shown in console */
+    description?: string;
+    /** Memory limit in MB (default: 150, max: 512) */
+    memoryMb?: number;
+    /** Execution timeout in seconds (default: 30, max: 120) */
+    timeoutSeconds?: number;
+    /** Per-function env var overrides (merged with project env vars) */
+    envVars?: Record<string, string>;
+    /** Whether invocations require Sylphx platform auth (default: false) */
+    requireAuth?: boolean;
+    /** Target environment slug (default: 'production') */
+    environment?: string;
+}
+interface FunctionRecord {
+    id: string;
+    name: string;
+    displayName: string | null;
+    description: string | null;
+    status: FunctionStatus;
+    version: number;
+    runtime: FunctionRuntime;
+    memoryMb: number;
+    timeoutSeconds: number;
+    requireAuth: boolean;
+    invocationCount: number;
+    errorCount: number;
+    lastInvokedAt: string | null;
+    /** Invocation URL */
+    url: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface FunctionDeployResult {
+    id: string;
+    name: string;
+    version: number;
+    status: FunctionStatus;
+    /** The live invocation URL */
+    url: string;
+}
+interface FunctionInvokeOptions {
+    /** HTTP method (default: POST) */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body (JSON-serialized automatically) */
+    body?: unknown;
+    /** Query parameters appended to the URL */
+    query?: Record<string, string>;
+}
+interface FunctionListOptions {
+    /** Filter by status */
+    status?: FunctionStatus;
+    /** Environment slug (default: 'production') */
+    environment?: string;
+    /** Max results (default: 50) */
+    limit?: number;
+}
+interface FunctionLogsOptions {
+    /** Maximum log entries to return (default: 100) */
+    limit?: number;
+    /** Only return errors */
+    errorsOnly?: boolean;
+    /** ISO timestamp — only logs after this time */
+    since?: string;
+}
+interface FunctionLogEntry {
+    id: string;
+    status: 'success' | 'error' | 'timeout';
+    statusCode: number | null;
+    durationMs: number | null;
+    method: string;
+    path: string | null;
+    errorMessage: string | null;
+    createdAt: string;
+}
+declare const FunctionsClient: {
+    /**
+     * Deploy (create or update) a function.
+     *
+     * If a function with the same name already exists, it is updated
+     * (version number incremented, code replaced atomically).
+     *
+     * @example
+     * ```typescript
+     * const fn = await FunctionsClient.deploy(config, {
+     *   name: 'send-webhook',
+     *   code: `
+     *     export default async (req: Request) => {
+     *       const body = await req.json()
+     *       await fetch(body.url, { method: 'POST', body: JSON.stringify(body.payload) })
+     *       return Response.json({ ok: true })
+     *     }
+     *   `,
+     *   timeoutSeconds: 10,
+     * })
+     * console.log('Deployed:', fn.url)
+     * ```
+     */
+    readonly deploy: (config: SylphxConfig, options: FunctionDeployOptions) => Promise<FunctionDeployResult>;
+    /**
+     * Get a function by name.
+     */
+    readonly get: (config: SylphxConfig, name: string) => Promise<FunctionRecord>;
+    /**
+     * List all functions for this project.
+     */
+    readonly list: (config: SylphxConfig, options?: FunctionListOptions) => Promise<FunctionRecord[]>;
+    /**
+     * Delete a function permanently.
+     */
+    readonly delete: (config: SylphxConfig, name: string) => Promise<void>;
+    /**
+     * Invoke a function from server-side code.
+     *
+     * For client-side invocations, call the function URL directly via fetch().
+     *
+     * @example
+     * ```typescript
+     * const result = await FunctionsClient.invoke(config, 'process-order', {
+     *   body: { orderId: '123', userId: 'user_abc' },
+     * })
+     * ```
+     */
+    readonly invoke: <T = unknown>(config: SylphxConfig, name: string, body?: unknown, options?: FunctionInvokeOptions) => Promise<T>;
+    /**
+     * Retrieve recent invocation logs for a function.
+     *
+     * @example
+     * ```typescript
+     * const logs = await FunctionsClient.logs(config, 'send-webhook', { errorsOnly: true })
+     * for (const entry of logs) {
+     *   console.log(`${entry.status} ${entry.durationMs}ms`, entry.errorMessage)
+     * }
+     * ```
+     */
+    readonly logs: (config: SylphxConfig, name: string, options?: FunctionLogsOptions) => Promise<FunctionLogEntry[]>;
+};
+
 /**
  * Platform ID utilities for the Sylphx SDK
  *
@@ -20483,14 +20827,14 @@ declare function getStreams(): StreamsClient;
  * Sylphx Server SDK
  *
  * Server-side operations using REST API for type safety.
- * Uses Secret Key for authentication - NEVER expose this to client-side.
+ * Uses connection URL (sylphx://sk_*@slug.sylphx.com) for authentication.
  *
  * @example
  * ```typescript
  * import { createServerClient, verifyWebhook } from '@sylphx/sdk/server'
  *
- * const client = createServerClient({
- *   secretKey: process.env.SYLPHX_SECRET_KEY!,
+ * const client = createServerRestClient({
+ *   secretKey: process.env.SYLPHX_SECRET_URL!,
  * })
  *
  * // REST API calls
@@ -20516,30 +20860,23 @@ interface ServerConfig {
     revalidate?: number;
 }
 /**
- * Create a Server Client for platform operations.
+ * Create a Server REST Client for type-safe API calls.
  *
- * Uses REST API for type-safe API calls.
- * The secret key identifies the app — no separate app ID needed.
+ * For the new connection URL API, use `createServerClient()` from '@sylphx/sdk'.
+ * This function creates an openapi-fetch REST client from a raw secret key.
  *
  * @example
  * ```typescript
- * const client = createServerClient({
- *   secretKey: process.env.SYLPHX_SECRET_KEY!,
+ * const client = createServerRestClient({
+ *   secretKey: 'sk_prod_...',
  * })
  *
- * // Billing
  * const { data: plans } = await client.GET('/billing/plans')
- * const { data: subscription } = await client.GET('/billing/subscription')
- *
- * // Analytics
- * await client.POST('/analytics/track', {
- *   body: { events: [{ event: 'purchase', properties: { amount: 99 } }] }
- * })
  * ```
  */
-declare function createServerClient(config: ServerConfig): RestClient;
+declare function createServerRestClient(config: ServerConfig): RestClient;
 /**
- * Create a Server Client with user context (access token)
+ * Create a Server REST Client with user context (access token)
  */
 declare function createAuthenticatedServerClient(config: ServerConfig, accessToken: string): RestClient;
 /**
@@ -20937,4 +21274,4 @@ declare function getDatabaseConnection(options: AuthenticatedFetchOptions): Prom
  */
 declare function getDatabaseStatus(options: AuthenticatedFetchOptions): Promise<DatabaseStatusInfo>;
 
-export { type AIClient, type AIClientOptions, type AppConfig, type AppMetadata, type ChannelHelper, type ChatCompletionChunk, type ChatCompletionOptions, type ChatCompletionResponse, type ChatCompletionStreamOptions, type ChatMessage, type ConsentType, type DatabaseConnectionInfo, type DatabaseStatusInfo, type EmbeddingOptions, type EmbeddingResponse, type EngagementLeaderboardEntry, type EngagementLeaderboardResult, type EnvironmentType, type FeatureFlagDefinition, type GetAppConfigOptions, type KeyType, type KeyValidationResult, type KvClient, type KvClientOptions, type KvRateLimitResult, type KvSetOptions, type KvZMember, type ModelInfo, type ModelsResponse, type OAuthProviderInfo, type Plan, type ReferralLeaderboardEntry, type ReferralLeaderboardResult, type RestClient, type RestClientConfig as ServerClientConfig, type ServerConfig, type StreamHistoryOptions, type StreamMessage, type StreamsClient, type StreamsClientOptions, type WebhookPayload, type WebhookVerifyOptions, type WebhookVerifyResult, createAI, createAuthenticatedServerClient, createKv, createServerClient, createStreams, createWebhookHandler, decodeUserId, detectEnvironment, detectKeyType, encodeUserId, getAI, getAppConfig, getAppMetadata, getConsentTypes, getCookieNamespace, getDatabaseConnection, getDatabaseStatus, getEngagementLeaderboard, getFeatureFlags, getJwks, getKv, getOAuthProviders, getOAuthProvidersWithInfo, getPlans, getReferralLeaderboard, getStreams, isAppId, isDevelopmentKey, isDevelopmentRuntime, isProductionKey, isSecretKey, resetJwksCache, validateAndSanitizeAppId, validateAndSanitizeKey, validateAndSanitizeSecretKey, validateAppId, validateKey, validateSecretKey, verifyAccessToken, verifyWebhook };
+export { type AIClient, type AIClientOptions, type AppConfig, type AppMetadata, type ChannelHelper, type ChatCompletionChunk, type ChatCompletionOptions, type ChatCompletionResponse, type ChatCompletionStreamOptions, type ChatMessage, type ConsentType, type DatabaseConnectionInfo, type DatabaseStatusInfo, type EmbeddingOptions, type EmbeddingResponse, type EngagementLeaderboardEntry, type EngagementLeaderboardResult, type EnvironmentType, type FeatureFlagDefinition, type FunctionDeployOptions, type FunctionDeployResult, type FunctionInvokeOptions, type FunctionListOptions, type FunctionLogEntry, type FunctionLogsOptions, type FunctionRecord, type FunctionRuntime, type FunctionStatus, FunctionsClient, type GetAppConfigOptions, InvalidConnectionUrlError, type KeyType, type KeyValidationResult, type KvClient, type KvClientOptions, type KvRateLimitResult, type KvSetOptions, type KvZMember, type ModelInfo, type ModelsResponse, type OAuthProviderInfo, type Plan, type ReferralLeaderboardEntry, type ReferralLeaderboardResult, type RestClient, type RestClientConfig as ServerClientConfig, type ServerConfig, type StreamHistoryOptions, type StreamMessage, type StreamsClient, type StreamsClientOptions, type SylphxClientInput, type SylphxConfig, type WebhookPayload, type WebhookVerifyOptions, type WebhookVerifyResult, createAI, createAuthenticatedServerClient, createClient, createKv, createServerClient, createServerRestClient, createStreams, createWebhookHandler, decodeUserId, detectEnvironment, detectKeyType, encodeUserId, getAI, getAppConfig, getAppMetadata, getConsentTypes, getCookieNamespace, getDatabaseConnection, getDatabaseStatus, getEngagementLeaderboard, getFeatureFlags, getJwks, getKv, getOAuthProviders, getOAuthProvidersWithInfo, getPlans, getReferralLeaderboard, getStreams, isAppId, isDevelopmentKey, isDevelopmentRuntime, isProductionKey, isSecretKey, resetJwksCache, validateAndSanitizeAppId, validateAndSanitizeKey, validateAndSanitizeSecretKey, validateAppId, validateKey, validateSecretKey, verifyAccessToken, verifyWebhook };