@promte/app-library 0.1.7 → 0.1.10

package/README.md

@@ -60,6 +60,23 @@ await client.data().ref("sessions/session-1/events").push({
 });
 ```
 
+## Backend functions
+
+Call an approved app function or a configured shared-function alias after the provider is ready:
+
+```ts
+const { ready } = usePromte();
+const client = usePromteClient();
+if (ready) {
+  const output = await client.functions.invoke("hello", { name: "Ada" });
+  // output is the handler result, not the administration run envelope.
+}
+```
+
+The running app is bound to its authorized release. In coding preview, calls use the saved draft and the test environment, which can contact real test APIs. Personal sign-in, workspace access and current function governance are required. Credentials stay in administrator-managed connections and must never be placed in browser code.
+
+See [App backend functions](../docs/app-functions.md) for manifests, handlers, controlled connections, data scopes, testing, releases, sharing and schedules.
+
 ## Models/capabilities
 
 You can fetch configured models/capabilities from backend:
@@ -128,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,12 +8,78 @@ 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>;
 
+/** A stored file. Names may contain folders, e.g. "corpus/2024/report.pdf". */
+export declare type AppFile = {
+    id: string;
+    name: string;
+    contentType: string;
+    size: number;
+    sha256: string;
+    createdAt: string;
+    updatedAt: string;
+};
+
+/**
+ * File storage for larger or binary content (documents, images, exports).
+ * "private" files belong to the signed-in user; "public" files are shared in the
+ * app workspace and only workspace administrators can change them.
+ * Uploading a file with an existing name replaces it.
+ */
+export declare type AppFiles = {
+    upload(file: Blob, options?: {
+        name?: string;
+        contentType?: string;
+        signal?: AbortSignal;
+    }): Promise<AppFile>;
+    list(options?: {
+        prefix?: string;
+    }): Promise<AppFile[]>;
+    download(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Blob>;
+    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;
@@ -59,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[];
@@ -160,8 +233,28 @@ 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: {
+        invoke<TInput = unknown, TResult = unknown>(name: string, input: TInput): Promise<TResult>;
+    };
     getBackendUrl(): string | null;
     models(req?: PromteModelsRequest): Promise<PromteModelInfo[]>;
     chatCompletions(req: ChatCompletionsRequest): Promise<ChatCompletionsResponse>;
@@ -190,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;
@@ -199,7 +295,21 @@ export declare type PromteClient = {
         update(shareId: string, snapshot: TranslatorLiveShareSnapshot): Promise<void>;
         revoke(shareId: string): Promise<void>;
     };
-    data(scope?: AppDataScope): AppDataRef;
+    guardrails: {
+        check(value: unknown): Promise<PromteGuardrailsResult>;
+    };
+    /** 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 = {
@@ -211,6 +321,43 @@ 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 = {
+    enabled: boolean;
+    allowed: boolean;
+    outcome: "allow" | "warn" | "block";
+    checks: Array<{
+        id: string;
+        mode: "warn" | "block";
+        result: "violation" | "inconclusive";
+        matches?: number;
+    }>;
+    revision: string;
 };
 
 export declare type PromteHandshakeState = "booting" | "waiting_for_settings" | "waiting_for_token" | "ready";
@@ -250,6 +397,10 @@ export declare type PromteSettings = {
     backendUrl: string;
     parentOrigin?: string;
     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 = {
@@ -257,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";
@@ -284,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;
@@ -303,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;
@@ -320,6 +539,10 @@ export declare type UsePromteModelsOptions = PromteModelsRequest & {
 
 export declare function usePromteSettings(): PromteSettings;
 
+/**
+ * @deprecated Promte sends backend requests for the app and no longer gives
+ * the app a token, so this returns null inside current Promte versions.
+ */
 export declare function usePromteToken(): string;
 
 export declare function usePromteUser(): PromteUser;