@hailer/app-sdk 2.8.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/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/permission.d.ts

@@ -25,6 +25,6 @@ export declare class PermissionApi {
      * @throws {HailerError} if the request fails
      */
     map: ({ workspaceId }?: {
-        workspaceId?: string;
+        workspaceId?: string | undefined;
     }) => Promise<PermissionMap>;
 }

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]: {
@@ -426,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.8.0",
+  "version": "2.9.0",
   "description": "SDK for building Hailer Apps",
   "author": "",
   "license": "ISC",