@hailer/app-sdk 2.7.0 → 2.9.0

package/lib/hailer-api.d.ts

@@ -15,6 +15,7 @@ import { Payment } from './modules/payment';
 import { Admin } from './modules/admin';
 import { MetricsApi } from './modules/metrics';
 import { HttpApi } from './modules/http';
+import { CredentialApi } from './modules/credential';
 export interface Options {
     /** When connected is called the host is ready to receive calls */
     connected?: () => void;
@@ -52,6 +53,8 @@ export declare class HailerApi {
     metrics: MetricsApi;
     /** HTTP proxy for making authenticated HTTP/WebSocket requests through the parent frame */
     http: HttpApi;
+    /** Securely store and retrieve credentials (API keys, username/password pairs, etc.) */
+    credential: CredentialApi;
     /** All public endpoints, which can be accessed while not logged in to Hailer. */
     public: HailerPublicApi;
     /** User interface commands */

package/lib/modules/activity.d.ts

@@ -22,10 +22,7 @@ export declare class ActivityApi {
     /**
      * Gets single activity
      *
-     * @param activityId activity Id of the process specified in processId
-     * @param processId Process where the activityId is
-     * @param phaseId Phase where the activityId is in process specified by processId
-     * @param options options containing apiVersion
+     * @param activityId Id of the activity to fetch
      *
      * @returns Hailer activity information or undefined if no activity is found
      *
@@ -65,7 +62,6 @@ export declare class ActivityApi {
      * Removes activities
      *
      * @param activities Ids of activities to be removed
-     * @param options options containing apiVersion
      *
      * @returns The number of removed activities
      *

package/lib/modules/admin.d.ts

@@ -131,6 +131,15 @@ export declare class Admin {
      * @throws {HailerError} if request fails, workspace not found, or user not authorized
      */
     updateWorkspaceOverrides(request: AdminUpdateOverridesRequest): Promise<boolean>;
+    /**
+     * Updates workspace marketplace settings
+     *
+     * @param request AdminUpdateMarketplaceSettingsRequest containing workspaceId and settings
+     *
+     * @returns boolean indicating success
+     *
+     * @throws {HailerError} if request fails, workspace not found, or user not authorized
+     */
     updateWorkspaceMarketplaceSettings(request: AdminUpdateMarketplaceSettingsRequest): Promise<boolean>;
     /**
      * Lists token transactions with filtering, pagination, and statistics
@@ -162,7 +171,26 @@ export declare class Admin {
      * @throws {HailerError} if request fails, purchase not found, or not a Hailer invoice purchase
      */
     updateInvoiceHandled(request: AdminInvoiceUpdateHandledRequest): Promise<AdminInvoiceUpdateHandledResponse>;
+    /**
+     * Links a subscription purchase to its activity
+     *
+     * @param purchaseId The purchase to update
+     * @param subscriptionActivityId The activity id to associate with the subscription
+     *
+     * @returns boolean indicating success
+     *
+     * @throws {HailerError} if request fails or user not authorized
+     */
     setSubscriptionActivityId(purchaseId: string, subscriptionActivityId: string): Promise<boolean>;
+    /**
+     * Lists revenue for a given month with optional filtering and pagination
+     *
+     * @param request AdminRevenueListRequest containing month, year, and optional filter/options
+     *
+     * @returns AdminRevenueListResponse with revenue rows and totals
+     *
+     * @throws {HailerError} if request fails or user not authorized
+     */
     listMonthlyRevenue(request: AdminRevenueListRequest): Promise<AdminRevenueListResponse>;
     /**
      * Gets dashboard statistics including counts for users, workspaces, activities, and messages

package/lib/modules/credential.d.ts

@@ -0,0 +1,48 @@
+import { Client } from '@wishcore/wish-rpc';
+import { CredentialCreateResponse, CredentialData, CredentialDetails, CredentialListItem, CredentialType, CredentialUpdate } from '../types';
+/**
+ * Securely store and retrieve credentials — API keys, username/password pairs,
+ * or any custom key-value secret.
+ *
+ * Every operation is scoped to credentials bound to your app: the host tags each
+ * credential you create with your app's id and re-checks that tag on every read
+ * and write, so you can never reach another app's credentials. Credentials
+ * created through the SDK are always **personal** — visible only to the acting
+ * user — and cannot be deleted through the SDK.
+ *
+ * A workspace app additionally sees, in `list`, the workspace credentials tagged
+ * with it that the acting user may read, and can `get` them; those cannot be
+ * modified through the SDK.
+ *
+ * `credential.get` returns the decrypted payload directly — there is no token
+ * exchange.
+ */
+export declare class CredentialApi {
+    private client;
+    constructor(client: Client);
+    /**
+     * Store a new encrypted credential. The credential is personal (owner-only)
+     * and is automatically bound to your app — the host forces the app
+     * association and drops any workspace or reader association.
+     *
+     * @throws {HailerError} if the request fails or the caller lacks permission
+     */
+    create(name: string, type: CredentialType, secret: CredentialData): Promise<CredentialCreateResponse>;
+    /**
+     * List your app's credentials. Encrypted fields are never returned. Results
+     * are always scoped to credentials bound to your app.
+     */
+    list(): Promise<CredentialListItem[]>;
+    /**
+     * Fetch and decrypt one of your app's credentials. The plaintext payload is
+     * returned directly in the RPC response — no token exchange.
+     */
+    get<T extends CredentialData = CredentialData>(credentialId: string): Promise<CredentialDetails<T>>;
+    /**
+     * Rename or rotate the secret of one of your app's personal credentials. At
+     * least one field must be provided in `updates`, and `secret` replaces the
+     * entire stored payload — there is no key-level merge. Workspace
+     * credentials cannot be updated through the SDK.
+     */
+    update(credentialId: string, updates: CredentialUpdate): Promise<boolean>;
+}

package/lib/modules/insight.d.ts

@@ -1,5 +1,5 @@
 import { Client } from '@wishcore/wish-rpc';
-import { InsightData, InsightDoc } from '../types';
+import { InsightData, InsightDoc, InsightQueryResult, InsightSource } from '../types';
 export declare class InsightApi {
     private client;
     constructor(client: Client);
@@ -32,4 +32,16 @@ export declare class InsightApi {
      * @throws {HailerError} if request is incorrect
      */
     update(insightId: string, update: Partial<InsightDoc>): Promise<InsightDoc[]>;
+    /**
+     * Run an ad-hoc query against Insight sources
+     *
+     * @param workspaceId the workspace to query within
+     * @param sources the Insight sources to query
+     * @param query the query string
+     *
+     * @returns query result with headers, rows, and details
+     *
+     * @throws {HailerError} if request is incorrect
+     */
+    query(workspaceId: string, sources: InsightSource[], query: string): Promise<InsightQueryResult>;
 }

package/lib/modules/metrics.d.ts

@@ -8,26 +8,22 @@ export interface MetricDefinition {
     supportsBreakdown: boolean;
 }
 export interface MetricData {
-    metricType: string;
-    timestamp: number;
-    current: {
-        value: number;
-        labels?: any;
-    };
+    /** Current scalar value (when not grouped into a series) */
+    value?: number;
+    /** Labels attached to the value */
+    labels?: Record<string, string>;
+    /** One series per group, each a list of { timestamp, value } */
     timeSeries?: Array<{
-        timestamp: number;
-        value: number;
+        labels: Record<string, string>;
+        values: Array<{
+            timestamp: number;
+            value: number;
+        }>;
     }>;
-    breakdown?: {
-        byWorkspace?: Record<string, number>;
-        byUser?: Record<string, number>;
-    };
-    metadata: {
-        scope?: any;
-        permissions?: any;
-        source: string;
-        executionTime?: number;
-    };
+    /** Set if this metric failed */
+    error?: boolean;
+    /** Failure detail */
+    errorMessage?: string;
 }
 export interface MetricOptions {
     workspaceId?: string;
@@ -39,17 +35,13 @@ export interface MetricOptions {
     interval?: '1m' | '5m' | '15m' | '30m' | '1h' | '5h';
     /** Aggregation function to apply */
     aggregation?: 'sum' | 'avg' | 'max' | 'min' | 'count' | 'rate' | 'increase';
-    /** Group results by specified labels (max 3). Allowed: userId, userRole, workspaceId, teamId, processId, workflowId, discussionId */
+    /** Group results by specified labels (max 3). Allowed: userId, userRole, workspaceId, teamId, processId, workflowId, discussionId, activityId, signal, type */
     groupBy?: string[];
     /** Limit results to top N values (1-100) */
     topk?: number;
-    /** Additional label filters. Allowed keys: userId, userRole, workspaceId, teamId, processId, workflowId, discussionId */
+    /** Additional label filters. Allowed keys: userId, userRole, workspaceId, teamId, processId, workflowId, discussionId, activityId, signal, type */
     labelFilters?: Record<string, string>;
 }
-export interface MetricListOptions {
-    category?: string;
-    includeDetails?: boolean;
-}
 export interface WorkspaceMetricsListOptions {
     /** Array of workspace IDs to look up */
     workspaceIds?: string[];
@@ -74,15 +66,14 @@ export declare class MetricsApi {
     constructor(client: Client);
     /**
    * Get list of available metrics for current user based on permissions
-   * @param options Optional filtering options
    * @returns Array of metric IDs or detailed metric definitions
    */
-    list(options?: MetricListOptions): Promise<string[] | MetricDefinition[]>;
+    list(): Promise<string[] | MetricDefinition[]>;
     /**
    * Get metrics data with optional Query Builder
    * @param metricTypes Single metric or array of metrics to fetch
    * @param options Optional filtering, time range, and Query Builder options
-   * @returns Metric data with values and optional time series
+   * @returns Array of metric data, one entry per requested metric (in request order)
    *
    * @example
    * // Simple query
@@ -98,7 +89,7 @@ export declare class MetricsApi {
    *   topk: 10
    * });
    */
-    get(metricTypes: string | string[], options?: MetricOptions): Promise<MetricData>;
+    get(metricTypes: string | string[], options?: MetricOptions): Promise<MetricData[]>;
     /**
    * Admin endpoints for metrics management
    */

package/lib/modules/ui/activity.d.ts

@@ -36,6 +36,10 @@ export declare class Activity {
         _id: string;
         name: string;
     } | null>;
-    /** Opens multiple activity edit view in Hailer sidebar */
-    editMultiple(activityIds: string[]): Promise<any>;
+    /**
+     * Opens multiple activity edit view in Hailer sidebar
+     *
+     * @param activityIds Ids of the activities to edit
+     */
+    editMultiple(activityIds: string[]): Promise<void>;
 }

package/lib/modules/ui/files.d.ts

@@ -7,7 +7,7 @@ import { Client } from '@wishcore/wish-rpc';
  * // New way (recommended):
  * import { FileApi } from '@hailer/app-sdk';
  * const fileApi = new FileApi(client);
- * const fileId = await fileApi.upload(base64Data, filename, { isPublic: false });
+ * const fileId = await fileApi.upload(file, filename, { isPublic: false });
  */
 export declare class Files {
     private client;

package/lib/modules/workflow.d.ts

@@ -22,11 +22,12 @@ export declare class WorkflowApi {
      */
     get(workflowId: string): Promise<Workflow>;
     /**
-     * Gets a single process from a workspace
+     * Installs a workflow (process) from a spec
      *
-     * @param processId the id of the process in question
+     * @param workflowSpec the workflow specification to install
+     * @param option optional target workspace
      *
-     * @returns the specified Hailer process
+     * @returns a map of template ids to the created ids
      *
      * @throws {HailerError} if request is incorrect
      */

package/lib/types.d.ts

@@ -295,6 +295,18 @@ export interface InsightResponseAsObjectItem {
     [key: string]: any;
 }
 export type InsightResponseAsObjects = InsightResponseAsObjectItem[];
+export type InsightSource = InsightWorkflowSource;
+export interface InsightQueryResult {
+    headers: string[];
+    rows: (string | number | null)[][];
+    /** Per-table breakdown of the temporary tables built from sources */
+    details: {
+        [tableName: string]: {
+            headers: string[];
+            rows: number;
+        };
+    };
+}
 export interface KanbanListResponse {
     map: {
         [phaseId: string]: {
@@ -334,6 +346,8 @@ export interface KanbanLoadResponse {
     phase: string;
 }
 export interface ActivityListOptions {
+    /** Workspace to resolve a workflow **key** in (keys are unique per workspace) */
+    workspaceId?: string;
     sortBy?: 'name' | 'created' | 'updated' | 'following' | 'owner' | 'team' | 'completedOn' | 'priority';
     sortOrder?: 'asc' | 'desc';
     limit?: number;
@@ -344,6 +358,8 @@ export interface ActivityListOptions {
     filters?: any;
 }
 export interface ActivityCreateOptions {
+    /** Workspace to resolve a workflow **key** in (keys are unique per workspace) */
+    workspaceId?: string;
     teamId?: string;
     fileIds?: string[];
     followerIds?: string[];
@@ -422,6 +438,59 @@ export interface Settings {
     theme: 'light' | 'dark';
     preferredLanguages: string[];
 }
+export type CredentialType = 'basic' | 'apiKey' | 'custom';
+export interface CredentialBasicData {
+    username: string;
+    password: string;
+}
+export interface CredentialApiKeyData {
+    apiKey: string;
+}
+/** Any JSON-serialisable value that can live inside a `custom` secret. */
+export type CredentialJsonValue = string | number | boolean | null | CredentialJsonValue[] | {
+    [key: string]: CredentialJsonValue;
+};
+/**
+ * Free-form secret for `custom` credentials — any JSON object with 1–50
+ * top-level keys.
+ */
+export interface CredentialCustomData {
+    [key: string]: CredentialJsonValue;
+}
+export type CredentialData = CredentialBasicData | CredentialApiKeyData | CredentialCustomData;
+/**
+ * Reader entry granting access to a workspace credential. Credentials created
+ * through the app SDK are personal and have no readers; readers only appear on
+ * workspace credentials bound to your app and surfaced in `list`.
+ */
+export type CredentialReader = `network_${string}` | `team_${string}` | `user_${string}`;
+export interface CredentialCreateResponse {
+    _id: string;
+}
+export interface CredentialListItem {
+    _id: string;
+    name: string;
+    type: CredentialType;
+    /** Set only on workspace credentials — absent on personal ones. */
+    workspaceId?: string;
+    /** The app the credential is bound to; always your own app's id. */
+    appId?: string;
+    /** Workspace credentials only. */
+    readers?: CredentialReader[];
+    createdBy: string;
+    created: number;
+    updated: number;
+}
+export interface CredentialUpdate {
+    name?: string;
+    /** Replaces the entire stored payload — there is no key-level merge. */
+    secret?: CredentialData;
+}
+/** Decrypted credential as returned by `credential.get`. */
+export interface CredentialDetails<T extends CredentialData = CredentialData> {
+    type: CredentialType;
+    secret: T;
+}
 export interface ApiInfo {
     /** Url of the Hailer instance hosting the API */
     hostUrl?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hailer/app-sdk",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "SDK for building Hailer Apps",
   "author": "",
   "license": "ISC",
@@ -16,7 +16,6 @@
     "watch": "concurrently --kill-others \"npm run watch-tsc\" \"npm run watch-esbuild\"",
     "watch-tsc": "tsc --watch",
     "watch-esbuild": "esbuild src/index.ts --bundle --format=esm --sourcemap --outfile=lib/app-sdk.js --watch",
-    "docs": "typedoc --entryPointStrategy expand ./src && open-cli ./docs/index.html",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint .",
@@ -47,8 +46,6 @@
     "eslint-plugin-diff": "2.1.7",
     "husky": "9.1.7",
     "lint-staged": "17.0.5",
-    "open-cli": "^9.0.0",
-    "typedoc": "^0.24.8",
     "typescript": "^5.1.3",
     "vitest": "^4.1.4"
   },