@sylphx/sdk 0.4.0 → 0.5.0

package/dist/react/index.d.cts

@@ -664,6 +664,32 @@ type NativeStepContext = {
      * @param duration  Human-readable duration: '5s', '30m', '2h', '1d'.
      */
     sleep(name: string, duration: string): Promise<void>;
+    /**
+     * Pause execution until a named event is published via TriggersClient.publishEvent().
+     *
+     * On first encounter: signals the platform to wait for the event; stops execution.
+     * After the event arrives: returns the event payload.
+     * If timeout expires before event arrives: returns null.
+     *
+     * @param name      Step identifier (must be unique within the handler).
+     * @param eventName The event name to listen for (e.g. 'user.approved').
+     * @param options   Optional timeout ('24h', '7d') and payload filter.
+     *
+     * @example Human-in-the-loop approval
+     * ```typescript
+     * const approval = await step.waitForEvent<{ approvedBy: string }>(
+     *   'wait-approval',
+     *   'order.approved',
+     *   { timeout: '48h', filter: { orderId: payload.orderId } },
+     * )
+     * if (!approval) throw new Error('Approval timed out')
+     * await notifyCustomer(approval.approvedBy)
+     * ```
+     */
+    waitForEvent<T = unknown>(name: string, eventName: string, options?: {
+        timeout?: string;
+        filter?: Record<string, unknown>;
+    }): Promise<T | null>;
 };
 /**
  * A named task definition registered with sylphx.tasks.define().
@@ -705,52 +731,54 @@ interface TaskRunStatus {
 }
 
 /**
- * SDK Configuration for Pure Functions
+ * SDK Configuration — ADR-055 Connection URL API
  *
- * This is the configuration object passed to pure SDK functions like
- * `track()`, `signIn()`, `getPlans()`, etc.
+ * v0.5.0: The primary entry point is `createClient(url)` which accepts
+ * a `sylphx://` connection URL. The old `createConfig({ ref, publicKey })`
+ * API is removed.
  *
- * ## Config Type Hierarchy
- *
- * - `SylphxConfig` (this) — Pure functions, server or client
- * - `SylphxClientConfig` — React hooks return value (appId, platformUrl only)
- * - `SylphxProviderProps` — React provider component props
- * - `SylphxMiddlewareConfig` — Next.js middleware options
- *
- * @example Server-side usage
- * ```ts
- * import { createConfig, track } from '@sylphx/sdk'
+ * @example
+ * ```typescript
+ * import { createClient } from '@sylphx/sdk'
  *
- * const config = createConfig({ secretKey: process.env.SYLPHX_SECRET_KEY! })
- * await track(config, { event: 'purchase', properties: { amount: 99 } })
+ * 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 (sk_*) — full access, server-side only.
-     * Embed project ref, env, and routing info (ADR-021).
-     * Get from Platform Console → Apps → Your App → Environments.
+     * Secret key — populated when credentialType is 'sk'.
+     * Backward-compatible alias for `credential` when credential is sk_*.
      */
     readonly secretKey?: string;
     /**
-     * Publishable key (pk_*) — client-safe, read-only access.
-     * Embeds project ref, env, and routing info (ADR-021).
-     * Get from Platform Console → Apps → Your App → Environments.
+     * Publishable key — populated when credentialType is 'pk'.
+     * Backward-compatible alias for `credential` when credential is pk_*.
      */
     readonly publicKey?: string;
     /**
-     * Project ref — 12-char lowercase alphanumeric string.
-     * Extracted from the key automatically (ADR-021).
-     * The SDK targets: https://{ref}.api.sylphx.com/v1
+     * @deprecated Use `slug`. Backward-compatible alias.
      */
     readonly ref: string;
-    /**
-     * Pre-computed base URL: https://{ref}.api.sylphx.com/v1
-     * Derived from the embedded ref in the key.
-     */
-    readonly baseUrl: string;
-    /** Optional: Current access token for authenticated requests */
-    readonly accessToken?: string;
 }
 
 interface components {
@@ -13404,8 +13432,8 @@ interface UseHasPermissionReturn {
  * Pure client-side permission check hook.
  *
  * Operates on a permissions array — no API call. Use with:
- * - JWT org_permissions claims (from token after switch-org)
- * - Permissions array from useMemberPermissions()
+ * - Permissions array from useMemberPermissions() hook
+ * - Any string[] of permission keys from your application state
  *
  * Accepts a single permission string or an array. When given an array,
  * returns both OR (`allowedAny`) and AND (`allowedAll`) results.

package/dist/react/index.d.ts

@@ -664,6 +664,32 @@ type NativeStepContext = {
      * @param duration  Human-readable duration: '5s', '30m', '2h', '1d'.
      */
     sleep(name: string, duration: string): Promise<void>;
+    /**
+     * Pause execution until a named event is published via TriggersClient.publishEvent().
+     *
+     * On first encounter: signals the platform to wait for the event; stops execution.
+     * After the event arrives: returns the event payload.
+     * If timeout expires before event arrives: returns null.
+     *
+     * @param name      Step identifier (must be unique within the handler).
+     * @param eventName The event name to listen for (e.g. 'user.approved').
+     * @param options   Optional timeout ('24h', '7d') and payload filter.
+     *
+     * @example Human-in-the-loop approval
+     * ```typescript
+     * const approval = await step.waitForEvent<{ approvedBy: string }>(
+     *   'wait-approval',
+     *   'order.approved',
+     *   { timeout: '48h', filter: { orderId: payload.orderId } },
+     * )
+     * if (!approval) throw new Error('Approval timed out')
+     * await notifyCustomer(approval.approvedBy)
+     * ```
+     */
+    waitForEvent<T = unknown>(name: string, eventName: string, options?: {
+        timeout?: string;
+        filter?: Record<string, unknown>;
+    }): Promise<T | null>;
 };
 /**
  * A named task definition registered with sylphx.tasks.define().
@@ -705,52 +731,54 @@ interface TaskRunStatus {
 }
 
 /**
- * SDK Configuration for Pure Functions
+ * SDK Configuration — ADR-055 Connection URL API
  *
- * This is the configuration object passed to pure SDK functions like
- * `track()`, `signIn()`, `getPlans()`, etc.
+ * v0.5.0: The primary entry point is `createClient(url)` which accepts
+ * a `sylphx://` connection URL. The old `createConfig({ ref, publicKey })`
+ * API is removed.
  *
- * ## Config Type Hierarchy
- *
- * - `SylphxConfig` (this) — Pure functions, server or client
- * - `SylphxClientConfig` — React hooks return value (appId, platformUrl only)
- * - `SylphxProviderProps` — React provider component props
- * - `SylphxMiddlewareConfig` — Next.js middleware options
- *
- * @example Server-side usage
- * ```ts
- * import { createConfig, track } from '@sylphx/sdk'
+ * @example
+ * ```typescript
+ * import { createClient } from '@sylphx/sdk'
  *
- * const config = createConfig({ secretKey: process.env.SYLPHX_SECRET_KEY! })
- * await track(config, { event: 'purchase', properties: { amount: 99 } })
+ * 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 (sk_*) — full access, server-side only.
-     * Embed project ref, env, and routing info (ADR-021).
-     * Get from Platform Console → Apps → Your App → Environments.
+     * Secret key — populated when credentialType is 'sk'.
+     * Backward-compatible alias for `credential` when credential is sk_*.
      */
     readonly secretKey?: string;
     /**
-     * Publishable key (pk_*) — client-safe, read-only access.
-     * Embeds project ref, env, and routing info (ADR-021).
-     * Get from Platform Console → Apps → Your App → Environments.
+     * Publishable key — populated when credentialType is 'pk'.
+     * Backward-compatible alias for `credential` when credential is pk_*.
      */
     readonly publicKey?: string;
     /**
-     * Project ref — 12-char lowercase alphanumeric string.
-     * Extracted from the key automatically (ADR-021).
-     * The SDK targets: https://{ref}.api.sylphx.com/v1
+     * @deprecated Use `slug`. Backward-compatible alias.
      */
     readonly ref: string;
-    /**
-     * Pre-computed base URL: https://{ref}.api.sylphx.com/v1
-     * Derived from the embedded ref in the key.
-     */
-    readonly baseUrl: string;
-    /** Optional: Current access token for authenticated requests */
-    readonly accessToken?: string;
 }
 
 interface components {
@@ -13404,8 +13432,8 @@ interface UseHasPermissionReturn {
  * Pure client-side permission check hook.
  *
  * Operates on a permissions array — no API call. Use with:
- * - JWT org_permissions claims (from token after switch-org)
- * - Permissions array from useMemberPermissions()
+ * - Permissions array from useMemberPermissions() hook
+ * - Any string[] of permission keys from your application state
  *
  * Accepts a single permission string or an array. When given an array,
  * returns both OR (`allowedAny`) and AND (`allowedAll`) results.