@promte/app-library

Docs for using the app DB API in embedded apps.

What "DB" means here

In this library, DB access is exposed as:

const client = usePromteClient();
const db = client.data(); // default scope: "private"

Scopes

• private (default): data is scoped per user.
• public: shared for the whole workspace.
  • Reads are allowed for users with workspace access.
  • Writes (set, update, remove, push) require workspace admin/owner.

const privateDb = client.data(); // same as client.data("private")
const publicDb = client.data("public");

Paths and refs

Use slash-separated paths:

const settingsRef = client.data("public").ref("translator/settings");

Path normalization trims spaces and removes extra slashes, so " /a//b/ " becomes "a/b".

Core operations

// Read
const settings = await client.data("public").ref("translator/settings").get();

// Set/replace value at path
await client.data("public").ref("translator/settings").set({
  temperature: 0.2,
});

// Update multiple child paths relative to current ref
await client.data("public").ref("translator").update({
  "settings/temperature": 0.3,
  "features/context": true,
});

// Remove path
await client.data("public").ref("translator/features").remove();

// Push into array at path (creates array if missing/not array)
await client.data().ref("sessions/session-1/events").push({
  type: "message",
  at: Date.now(),
});

Models/capabilities

You can fetch configured models/capabilities from backend:

const client = usePromteClient();
const allModels = await client.models();
const llmsOnly = await client.models({ type: "llm", configuredOnly: true });
const embeddingsOnly = await client.models({
  type: "embedding",
  configuredOnly: true,
});

Or use the built-in hook:

const { models, loading, error, reload } = usePromteModels({
  type: "llm",
  configuredOnly: true,
});

Each model includes id, label, type (llm | embedding | image | stt | tts) and configured.

Embeddings

Embeddings use the same app token/auth flow as LLM requests. Fetch an available embedding model, then create embeddings:

const client = usePromteClient();
const [model] = await client.models({
  type: "embedding",
  configuredOnly: true,
});

const response = await client.embeddings.create({
  model: model.id,
  input: ["First text", "Second text"],
});

const vectors = response.data.map((item) => item.embedding);

Knowledge search

Apps can search an assistant/workspace knowledge base directly:

const client = usePromteClient();

const response = await client.knowledge.search({
  workspaceId: "assistant-workspace-id",
  query: "Hvad gælder for carporte i BR18?",
  maxResults: 8,
  generateSearchQuery: true,
});

for (const result of response.results) {
  console.log(result.title, result.text, result.sourceUrl);
}

If workspaceId is omitted, the search uses the current app workspace. Searching another workspace requires that the current user has access to that workspace. Public app tokens can only search their own workspace.

Return behavior

• get() returns the value at the current path, or null if missing.
• Mutations (set, update, remove, push) return the updated scope object.

Common patterns

// Save one record by id
await client.data().ref(`sessions/${sessionId}`).set(session);

// List records under a collection-like object
const sessionsObj = await client.data().ref("sessions").get();
const sessions = sessionsObj ? Object.values(sessionsObj) : [];

Errors to expect

• Promte settings not received yet / Promte token not received yet: provider handshake not ready.
• Admin only: trying to write to public scope without admin rights.
• update requires an object: ref.update(...) got a non-object input.
• push requires a path: attempted client.data().push(...) without a ref path.