@hailer/app-sdk 2.13.0 → 2.15.0

package/lib/hailer-api.d.ts

@@ -16,6 +16,7 @@ import { Admin } from './modules/admin';
 import { MetricsApi } from './modules/metrics';
 import { HttpApi } from './modules/http';
 import { CredentialApi } from './modules/credential';
+import { ActionApi } from './modules/action';
 export interface Options {
     /** When connected is called the host is ready to receive calls */
     connected?: () => void;
@@ -55,6 +56,8 @@ export declare class HailerApi {
     http: HttpApi;
     /** Securely store and retrieve credentials (API keys, username/password pairs, etc.) */
     credential: CredentialApi;
+    /** Trigger workspace actions and read back their runs */
+    action: ActionApi;
     /** All public endpoints, which can be accessed while not logged in to Hailer. */
     public: HailerPublicApi;
     /** User interface commands */

package/lib/index.d.ts

@@ -1,3 +1,4 @@
 export { HailerApi } from './hailer-api';
 export * from './types';
 export * from './modules/metrics';
+export * from './modules/file';

package/lib/modules/action.d.ts

@@ -0,0 +1,22 @@
+import { Client } from '@wishcore/wish-rpc';
+import { ActionRun, ActionTriggerTarget } from '../types';
+export declare class ActionApi {
+    private client;
+    constructor(client: Client);
+    /**
+     * Triggers an action. Waits up to 25 s; a longer run is returned still
+     * in progress and must be polled with `getRun`.
+     *
+     * @param target one of `actionId` or `key`, plus optional `workspaceId` (defaults to the app's workspace)
+     * @param input delivered as the payload of a `manual` event
+     *
+     * @throws {HailerError} if the action is not found or the user may not trigger it
+     */
+    trigger(target: ActionTriggerTarget, input?: unknown): Promise<ActionRun>;
+    /**
+     * Gets one run. Non-admins can only read runs they triggered.
+     *
+     * @throws {HailerError} if the run is not found or the user may not read it
+     */
+    getRun(runId: string): Promise<ActionRun>;
+}

package/lib/modules/file.d.ts

@@ -10,9 +10,74 @@ export interface FileResponse {
 export interface UploadOptions {
     /** Whether the file should be publicly accessible */
     isPublic?: boolean;
+    /**
+     * Scope the file to the app's workspace (irreversible). A scoped file is readable only by its owner,
+     * workspace admins and its readers; set readers with `setReaders`. Cannot be combined with `isPublic`,
+     * and not available to guests. This is the only way to scope a file.
+     */
+    scoped?: boolean;
+}
+/** Owner, workspace and readers of a file. `workspaceId` and `readers` are absent for an unscoped file. */
+export interface FileScope {
+    _id: string;
+    /** Owner of the file */
+    uid: string;
+    /** Workspace the file is scoped to */
+    workspaceId?: string;
+    /** Reader entries, see `FileApi.readers` */
+    readers?: string[];
+}
+export interface FileListOptions {
+    /** One keyword or up to 20. A keyword matches a case-insensitive substring of the file name or of any tag. */
+    search?: string | string[];
+    /** `all` (default) requires every keyword to match, `any` at least one */
+    matchType?: 'all' | 'any';
+    skip?: number;
+    /** 1-100, default 100 */
+    limit?: number;
+    sortBy?: 'name' | 'created';
+    reverse?: boolean;
 }
+export interface ScopedFile {
+    _id: string;
+    name: string;
+    /** Owner of the file */
+    uid: string;
+    workspaceId: string;
+    type?: string;
+    length?: number;
+    created?: number;
+    updated?: number;
+    tags?: string[];
+}
+export interface FileListResponse {
+    files: ScopedFile[];
+    hasMore: boolean;
+    total: number;
+}
+/**
+ * Builders for `setReaders` entries. Only full members of the app's workspace ever match a reader:
+ * guests never do, not even through a team or a `user_` entry.
+ */
+export declare const fileReaders: {
+    /** Every full member of the workspace */
+    workspace: (workspaceId: string) => string;
+    /** The full members of a team; guests in the team are skipped */
+    team: (teamId: string) => string;
+    /** A single full member; a guest is rejected */
+    user: (userId: string) => string;
+};
 export declare class FileApi {
     private client;
+    /** Builders for `setReaders` entries: `readers.workspace(id)`, `readers.team(id)`, `readers.user(id)` */
+    readonly readers: {
+        /** Every full member of the workspace */
+        workspace: (workspaceId: string) => string;
+        /** The full members of a team; guests in the team are skipped */
+        team: (teamId: string) => string;
+        /** A single full member; a guest is rejected */
+        user: (userId: string) => string;
+    };
     constructor(client: Client);
     /**
      * Gets a file by ID and returns it as base64 data
@@ -39,7 +104,8 @@ export declare class FileApi {
     /**
      * Appends tags to a file, deduping against the existing list.
      *
-     * Tags are case-sensitive free-form strings (trimmed, 1-64 characters, max 50 per file).
+     * Tags are case-sensitive free-form strings (trimmed, 1-64 characters, max 50 per file). On a scoped
+     * file only its owner or a workspace admin may change tags; readers can read them but not edit.
      *
      * @param fileId The ID of the file to tag
      * @param tags Tags to add
@@ -51,6 +117,7 @@ export declare class FileApi {
     addTags(fileId: string, tags: string[]): Promise<string[]>;
     /**
      * Removes tags from a file by case-sensitive exact match. Tags not present are silently ignored.
+     * On a scoped file only its owner or a workspace admin may change tags.
      *
      * @param fileId The ID of the file to untag
      * @param tags Tags to remove
@@ -60,5 +127,74 @@ export declare class FileApi {
      * @throws {HailerError} if validation fails or the file cannot be edited
      */
     removeTags(fileId: string, tags: string[]): Promise<string[]>;
+    /**
+     * Gets the owner, workspace and readers of a file you can read. Use it as an "is this file scoped?"
+     * probe: `workspaceId` is absent for an unscoped file.
+     *
+     * @param fileId The ID of the file
+     *
+     * @throws {HailerError} if the file does not exist or you cannot read it (guests cannot read scoped
+     *   files), or if it is scoped to a workspace other than the app's (403)
+     */
+    getScope(fileId: string): Promise<FileScope>;
+    /**
+     * Replaces the readers of a file scoped to the app's workspace. Files are scoped only at upload
+     * (`upload(..., { scoped: true })`); an unscoped file is refused (403) rather than scoped here.
+     *
+     * Requires being the file's owner (while a full member) or a workspace admin; not available to guests.
+     * A non-admin may only add teams they belong to. Every entry must belong to the app's workspace, and
+     * `user_` must name a full member, not a guest.
+     *
+     * @param fileId The ID of the file
+     * @param readers The complete new reader list (max 100); build entries with `readers.*`. Send `[]` to
+     *   leave only the owner and workspace admins.
+     *
+     * @returns The resulting scope
+     *
+     * @throws {HailerError} if validation fails, the file is not scoped to the app's workspace, or you may
+     *   not manage it
+     */
+    setReaders(fileId: string, readers: string[]): Promise<FileScope>;
+    /**
+     * Lists the scoped files of the app's workspace that the user can read: their own, those they are a
+     * reader of, or all of them for a workspace admin. Unscoped files are not listed.
+     *
+     * @param options Search by name/tags and paging
+     *
+     * @returns A page of files, whether more exist, and the total match count
+     *
+     * @throws {HailerError} if validation fails, or for a guest
+     */
+    list(options?: FileListOptions): Promise<FileListResponse>;
+    /**
+     * Transfers a file scoped to the app's workspace to another full member of it (not a guest). Workspace
+     * admins only. The previous owner loses access unless they are a reader.
+     *
+     * @param fileId The ID of the file
+     * @param userId The new owner
+     *
+     * @throws {HailerError} if you are not a workspace admin, the file is not scoped to the app's workspace,
+     *   or the user is not a full member
+     */
+    setOwner(fileId: string, userId: string): Promise<boolean>;
+    /**
+     * Permanently deletes files scoped to the app's workspace that you own. Ids of files owned by someone
+     * else are skipped without an error, even for a workspace admin; re-list to see what is left. If any id
+     * is not a file scoped to the app's workspace, the whole call is refused (403) and nothing is removed:
+     * an app can never delete the user's other files.
+     *
+     * @param fileIds 1-100 file ids
+     *
+     * @returns `true` once the request is processed
+     *
+     * @throws {HailerError} if validation fails, or any file is not scoped to the app's workspace
+     */
+    remove(fileIds: string[]): Promise<boolean>;
+    /**
+     * An older Hailer ignores the `scoped` upload argument and stores the file unscoped. Fail loudly rather
+     * than hand back a file the app believes is restricted. Only a missing `file.getScope` (wish-rpc code
+     * 300) or an unscoped result means an older Hailer; any other error is passed on as is.
+     */
+    private assertScoped;
     private toBase64;
 }

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

@@ -453,6 +453,42 @@ export interface Settings {
     theme: 'light' | 'dark';
     preferredLanguages: string[];
 }
+/** One of actionId or key. workspaceId is optional, needed with a key in a private app. */
+export interface ActionTriggerTarget {
+    actionId?: string;
+    key?: string;
+    workspaceId?: string;
+}
+/** `queued` and `running` are in progress, the rest are final. */
+export type ActionRunStatus = 'queued' | 'running' | 'completed' | 'runtime_error' | 'timeout' | 'output_limit' | 'infra_error' | 'cancelled' | 'config_error' | 'denied';
+export type ActionEvent = 'manual' | 'phase.activity-created' | 'phase.activity-updated' | 'phase.activity-moved' | 'workspace.member-joined' | 'workspace.member-left' | 'schedule.run';
+export declare const ACTION_RUN_ACTIVE_STATUSES: ActionRunStatus[];
+/** One run of an action. Fields marked "admins only" are absent for other users. */
+export interface ActionRun {
+    _id: string;
+    actionId: string;
+    workspaceId: string;
+    event: ActionEvent;
+    /** Absent on scheduled runs */
+    triggeredBy?: string;
+    status: ActionRunStatus;
+    exitCode?: number | null;
+    /** Return value of `execute(input)` */
+    output?: unknown;
+    /** Detail for abnormal statuses */
+    message?: string | null;
+    wallTimeMs?: number | null;
+    created: number;
+    finishedAt?: number | null;
+    /** Admins only */
+    arguments?: string;
+    /** Admins only */
+    stdout?: string | null;
+    /** Admins only */
+    stderr?: string | null;
+    /** Admins only */
+    execRunId?: string | null;
+}
 export type CredentialType = 'basic' | 'apiKey' | 'custom';
 export interface CredentialBasicData {
     username: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hailer/app-sdk",
-  "version": "2.13.0",
+  "version": "2.15.0",
   "description": "SDK for building Hailer Apps",
   "author": "",
   "license": "ISC",