@promte/app-library 0.1.8 → 0.1.10

package/README.md

@@ -145,6 +145,40 @@ If `workspaceId` is omitted, the search uses the current app workspace. Searchin
 another workspace requires that the current user has access to that workspace.
 Public app tokens can only search their own workspace.
 
+## Ask an assistant
+
+Apps can ask a Promte assistant. The assistant answers with its own prompt,
+model, tools and knowledge base, and the conversation appears in the
+assistant's logs and insights:
+
+```ts
+const first = await client.assistant.ask({
+  assistantId: "assistant-workspace-id",
+  question: "Hvad kan vi låne til en 6. klasse i fysik?",
+});
+console.log(first.answer, first.sources);
+
+// Follow-up in the same conversation
+await client.assistant.ask({
+  assistantId: "assistant-workspace-id",
+  conversationId: first.conversationId,
+  question: "Har I noget til indskolingen?",
+});
+```
+
+Signed-in users can ask assistants they have access to. Public apps can only
+ask assistants that are published publicly. The call waits for the full answer
+(no streaming). For structured data, ask the assistant to answer in JSON in its
+prompt or question and parse `answer`.
+
+Each visitor without login may ask 30 questions per 10 minutes from one IP
+address, and each app 2,000 questions per day. Above that the call fails with
+status 429 and the message `rate_limited`; show a friendly "try again later".
+
+`answer` is Markdown. Footnotes such as `^2^` or `^0,3^` point at
+`sources[2]`, `sources[0]` and `sources[3]`; the same source can appear more
+than once. `link` is empty for uploaded files, which have no public address.
+
 ## Return behavior
 
 - `get()` returns the value at the current path, or `null` if missing.

package/dist/index.d.ts

@@ -8,9 +8,17 @@ export declare type AppDataRef = {
     remove(): Promise<any>;
     push(value: any): Promise<any>;
     ref(path: string): AppDataRef;
+    /** "shared" scope only: every user's value at this path. */
+    getAll<T = any>(): Promise<AppSharedItem<T>[]>;
 };
 
-export declare type AppDataScope = "private" | "public";
+/**
+ * "private": only the signed-in user. "public": readable by everyone, only
+ * workspace administrators can change it. "shared": everyone reads all of it,
+ * each user writes only their own part (ref().getAll() returns every part),
+ * and workspace administrators can change anyone's part with { owner }.
+ */
+export declare type AppDataScope = "private" | "public" | "shared";
 
 export declare type AppDataUpdateMap = Record<string, any>;
 
@@ -46,6 +54,32 @@ export declare type AppFiles = {
     remove(id: string): Promise<void>;
 };
 
+export declare type AppFileScope = "private" | "public";
+
+/** One user's part of shared data. owner is a stable id, not an email. */
+export declare type AppSharedItem<T = any> = {
+    owner: string;
+    mine: boolean;
+    value: T;
+};
+
+export declare type AssistantAskRequest = {
+    /** The assistant workspace that answers. Public apps can only ask public assistants. */
+    assistantId: string;
+    question: string;
+    /** Continue an earlier conversation from a previous answer. */
+    conversationId?: string;
+};
+
+export declare type AssistantAskResponse = {
+    conversationId: string;
+    answer: string;
+    sources: {
+        title: string;
+        link: string;
+    }[];
+};
+
 export declare type AudioSttRequest = {
     file: File | Blob;
     language?: string;
@@ -91,6 +125,13 @@ export declare type AudioVoicesRequest = {
     locale?: string;
 };
 
+declare type AuthAction = "signIn" | "signUp" | "sendLoginLink" | "sendPasswordReset" | "completePasswordReset" | "signOut";
+
+declare type AuthRequest = (action: AuthAction, input?: {
+    email?: string;
+    password?: string;
+}) => Promise<void>;
+
 export declare type ChatCompletionsRequest = {
     model: string;
     messages: ChatMessage[];
@@ -192,6 +233,23 @@ export declare type PromteAppProviderProps = {
     };
 };
 
+/** Login for visitors of a public app, when the app's admins turned it on. */
+export declare type PromteAuthState = {
+    /** The app's admins turned on visitor login for this public app. */
+    loginEnabled: boolean;
+    methods: {
+        password: boolean;
+        magicLink: boolean;
+        signup: boolean;
+    };
+    /** A visitor is signed in. People signed in to Promte are never visitors. */
+    signedIn: boolean;
+    /** The visitor opened a password-reset link; call completePasswordReset. */
+    pendingPasswordReset: boolean;
+    /** The visitor opened a login or reset link that had expired or was already used. */
+    expiredLink: boolean;
+};
+
 export declare type PromteClient = {
     isReady(): boolean;
     functions: {
@@ -225,6 +283,9 @@ export declare type PromteClient = {
     knowledge: {
         search(req: KnowledgeSearchRequest): Promise<KnowledgeSearchResponse>;
     };
+    assistant: {
+        ask(req: AssistantAskRequest): Promise<AssistantAskResponse>;
+    };
     translatorLiveShare: {
         create(displayLanguage: string): Promise<{
             shareId: string;
@@ -237,8 +298,18 @@ export declare type PromteClient = {
     guardrails: {
         check(value: unknown): Promise<PromteGuardrailsResult>;
     };
-    data(scope?: AppDataScope): AppDataRef;
-    files(scope?: AppDataScope): AppFiles;
+    /** owner (from getAll) lets workspace administrators change another user's shared part. */
+    data(scope?: AppDataScope, options?: {
+        owner?: string;
+    }): AppDataRef;
+    files(scope?: AppFileScope): AppFiles;
+    email: {
+        /** Sends one email per recipient from "<app name> via Promte"; replies go to the signed-in user, or to replyTo for visitors without login. */
+        send(req: PromteEmailRequest): Promise<{
+            sent: number;
+        }>;
+    };
+    assets: SharedAssets;
 };
 
 declare type PromteCtxValue = {
@@ -250,6 +321,30 @@ declare type PromteCtxValue = {
     state: PromteHandshakeState;
     error: string | null;
     client: PromteClient;
+    auth: PromteAuthState;
+    authRequest: AuthRequest;
+};
+
+/** Thrown by client.email.send; code says why the email was not sent. */
+export declare class PromteEmailError extends Error {
+    code: PromteEmailErrorCode;
+    status: number;
+    constructor(code: PromteEmailErrorCode, status: number, message?: string);
+}
+
+export declare type PromteEmailErrorCode = "sign_in_required" | "invalid_recipient" | "too_many_recipients" | "invalid_subject" | "invalid_body" | "body_too_large" | "invalid_reply_to" | "recipient_not_allowed" | "email_disabled" | "rate_limited" | "email_not_configured" | "send_failed" | "app_policy_blocked" | "server_error";
+
+export declare type PromteEmailRequest = {
+    /** One address or up to 5. Only the signed-in user, members of the app, the app's visitor accounts and the app's fixed recipients. Visitors without login may only write to the fixed recipients. */
+    to: string | string[];
+    /** At most 200 characters. */
+    subject: string;
+    /** Plain text. Text and html together may be at most 50 KB. */
+    text: string;
+    /** Optional simple HTML: only p, br, strong, b, em, i, u, ul, ol, li, h1-h3, blockquote and <a href="https://...">; everything else is shown as text. */
+    html?: string;
+    /** Visitors without login only: the address replies should go to, for example one the visitor typed in. It is not verified and is marked as such in the mail. Signed-in users always get the replies themselves. */
+    replyTo?: string;
 };
 
 export declare type PromteGuardrailsResult = {
@@ -304,6 +399,8 @@ export declare type PromteSettings = {
     user?: PromteUser;
     /** Set by Promte pages that can send backend requests for the app. */
     fetchProxy?: boolean;
+    /** False when governance turned file downloads from apps off. */
+    allowDownloads?: boolean;
 };
 
 export declare type PromteUser = {
@@ -311,6 +408,15 @@ export declare type PromteUser = {
     isAdmin?: boolean;
     role?: string;
     workspaceId?: string;
+    /** Entra ID or FK Organisation groups, when the organisation and app share them. */
+    groups?: Array<{
+        id: string;
+        name?: string;
+    }>;
+    /** Roles from the organisation's login (for example Entra ID app roles). */
+    roles?: string[];
+    /** True for a visitor signed in to a public app with its own app login. */
+    visitor?: boolean;
 };
 
 export declare type ReasoningEffort = "minimal" | "low" | "medium" | "high";
@@ -338,6 +444,31 @@ export declare type ScrapeUrlResponse = {
     };
 };
 
+/** An organisation-wide asset (logo, font, image or style file) shared by all apps. */
+export declare type SharedAsset = {
+    name: string;
+    contentType: string;
+    size: number;
+    sha256: string;
+    description: string;
+    updatedAt: string;
+};
+
+/**
+ * Organisation assets uploaded by super administrators. Load them through
+ * these helpers: the app sandbox blocks direct remote image, font and style URLs.
+ */
+export declare type SharedAssets = {
+    list(): Promise<SharedAsset[]>;
+    get(name: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Blob>;
+    /** The asset as text, for CSS, JSON and text files. */
+    text(name: string): Promise<string>;
+    /** A cached object URL for img src, CSS url(...) or FontFace. */
+    url(name: string): Promise<string>;
+};
+
 export declare type TranslatorLiveShareLine = {
     id: string;
     speaker: string;
@@ -357,6 +488,40 @@ export declare type TranslatorLiveShareSnapshot = {
 
 export declare function usePromte(): PromteCtxValue;
 
+/**
+ * Visitor login for public apps. Build your own login UI with these functions;
+ * Promte checks passwords, stores accounts, sends the emails and keeps the
+ * session. Errors reject with an Error whose message is a code such as
+ * "invalid_credentials", "weak_password", "too_many_attempts", "expired_link"
+ * or "login_disabled". After signIn, usePromteUser() returns the visitor.
+ */
+export declare function usePromteAuth(): {
+    /** Signs in with email and password. */
+    signIn: (email: string, password: string) => Promise<void>;
+    /** Starts sign-up; the account is created when the visitor clicks the link in the email. */
+    signUp: (email: string, password: string) => Promise<void>;
+    /** Emails a single-use login link. Resolves even if the email has no account. */
+    sendLoginLink: (email: string) => Promise<void>;
+    /** Emails a link for choosing a new password. */
+    sendPasswordReset: (email: string) => Promise<void>;
+    /** Sets the new password after the visitor opened a reset link, and signs them in. */
+    completePasswordReset: (password: string) => Promise<void>;
+    signOut: () => Promise<void>;
+    /** The app's admins turned on visitor login for this public app. */
+    loginEnabled: boolean;
+    methods: {
+        password: boolean;
+        magicLink: boolean;
+        signup: boolean;
+    };
+    /** A visitor is signed in. People signed in to Promte are never visitors. */
+    signedIn: boolean;
+    /** The visitor opened a password-reset link; call completePasswordReset. */
+    pendingPasswordReset: boolean;
+    /** The visitor opened a login or reset link that had expired or was already used. */
+    expiredLink: boolean;
+};
+
 export declare function usePromteClient(): PromteClient;
 
 export declare function usePromteDarkMode(): boolean;