@hailer/app-sdk 2.9.0 → 2.14.0

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/activity.d.ts

@@ -1,5 +1,5 @@
 import { Client } from '@wishcore/wish-rpc';
-import { ActivityCreateOptions, ActivityListOptions, Activity, ActivityFieldUpdateValue, ActivityUpdateOptions, ActivityFieldValue, PrintRequest, PrintResponse } from '../types';
+import { ActivityCreateOptions, ActivityListOptions, Activity, ActivityFieldUpdateValue, ActivityUpdateOptions, ActivityFieldValue, PrintRequest, PrintOptions, PrintResponse } from '../types';
 import { Kanban } from './activity/kanban';
 import { Ball } from './activity/ball';
 export declare class ActivityApi {
@@ -76,10 +76,12 @@ export declare class ActivityApi {
      * @param requests[].templateId Template ID for regular templates
      * @param requests[].templateName Template name for multi-pdf templates (when templateId is empty)
      * @param requests[].savePdf Whether to save the generated PDF
+     * @param options.openNative Also open the document in the device's own viewer where the host supports it
+     *   (the Hailer Android app); see `openedNatively` in the response
      *
      * @returns PDF data with filename, base64 data, and mimeType
      *
      * @throws {HailerError} if request is incorrect
      */
-    print(requests: PrintRequest[]): Promise<PrintResponse>;
+    print(requests: PrintRequest[], options?: PrintOptions): Promise<PrintResponse>;
 }

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/types.d.ts

@@ -428,11 +428,26 @@ export interface PrintRequest {
     /** Whether to save the PDF to the file system */
     savePdf?: boolean;
 }
+export interface PrintOptions {
+    /**
+     * Open the generated document in the device's own viewer, where the host supports it.
+     * Currently only the Hailer Android app does: the document is saved to Downloads and opened
+     * in the system PDF viewer, where the user can print or share it. Elsewhere the document is
+     * only returned, as without this option; check `openedNatively` in the response.
+     */
+    openNative?: boolean;
+}
 export interface PrintResponse {
     filename: string;
     /** Base64-encoded document data */
     data: string;
     mimeType: string;
+    /**
+     * Only set when `openNative` was requested: `true` if the host handed the document to the
+     * device's own viewer, `false` if it couldn't (web, iOS). Older Hailer versions leave it unset,
+     * so treat anything but `true` as "not opened".
+     */
+    openedNatively?: boolean;
 }
 export interface Settings {
     theme: 'light' | 'dark';

package/package.json

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