@dropby/server 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simpllyf Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,235 @@
+# `@dropby/server`
+
+Server-side client for calling DropBy with your product's secret key. Use it from
+your authenticated backend to mint browser sessions and to operate on chat,
+ideas, asks, and evaluated configuration.
+
+## Installation
+
+```bash
+pnpm add @dropby/server
+```
+
+It has no dependencies and uses only the standard `fetch` and Web Crypto APIs.
+On Node.js it needs version 22.12 or newer.
+
+## Keys
+
+DropBy gives each product and environment three kinds of credential, all from
+the dashboard's API keys page:
+
+- **The secret key** (`sk_live_...` or `sk_test_...`) is for your backend only:
+  never ship it to a browser or a mobile app. It can do what you allowed when
+  you created it, such as `browser_session:create` to create browser sessions or
+  `config:read` to evaluate flags. Revoking it also ends the browser sessions it
+  created: open pages using them get `forbidden` until they reload, so switch
+  your backend to a new key before you revoke the old one.
+- **The public key** (`pk_live_...` or `pk_test_...`) is for the browser. It names
+  the product, the environment and the allowed origins, and grants nothing on
+  its own.
+- **The identity secret** belongs to one browser key and signs identity proofs
+  on your backend (below). Keep it there too; the proof it signs is readable in
+  the browser, so it carries no secrets.
+
+## Mint a browser session
+
+Derive the user and account from the host application's authenticated session,
+then create the DropBy session on the server. Do not copy a secret key to the
+browser, and do not let the browser choose the identity sent to this method.
+
+```ts
+import { createDropByServer } from "@dropby/server";
+
+type HostSession = {
+  user: { id: string; email?: string; name?: string };
+  account?: { id: string; name?: string };
+};
+
+// Implement this with the host application's session or request authentication.
+declare function authenticate(request: Request): Promise<HostSession | null>;
+
+export async function createDropBySessionResponse(request: Request): Promise<Response> {
+  const noStore = (body: string, status: number, extraHeaders: Record<string, string> = {}) =>
+    new Response(body, {
+      status,
+      headers: { "cache-control": "no-store", ...extraHeaders },
+    });
+
+  if (request.method !== "POST") {
+    return noStore("Method Not Allowed", 405, { allow: "POST" });
+  }
+
+  try {
+    const host = await authenticate(request);
+    if (!host) return noStore("Unauthorized", 401);
+
+    const secretKey = process.env.DROPBY_SECRET_KEY;
+    if (!secretKey) return noStore("DropBy is not configured", 500);
+
+    const dropby = createDropByServer({ secretKey });
+
+    const { session } = await dropby.browserSessions.create({
+      user: host.user,
+      ...(host.account ? { account: host.account } : {}),
+    });
+
+    // `session` is `{ sessionToken, expiresAt }`, what the browser's `auth` returns.
+    return Response.json(session, { headers: { "cache-control": "no-store" } });
+  } catch {
+    return noStore("DropBy session creation failed", 500);
+  }
+}
+```
+
+The endpoint is POST-only, returns `Allow: POST` with a 405 for other methods,
+and sets `Cache-Control: no-store` on success and every explicit error response.
+
+Omit `account` for a user-only product: the session then has no account.
+Everything the user does without one stays theirs under any account they later
+belong to. Deliver the session only over your authenticated application
+response.
+
+The client also exposes `ideas`, `asks`, `chat`, and `config` for server-side
+workflows. Ids are plain strings: one in a URL path is checked before anything is
+sent (`invalid_input`), and one in a request body is checked by the API (a 400
+naming the field).
+
+## Feature flags
+
+`config.evaluate` resolves every flag for a user and account, as the browser
+does for its session:
+
+<!-- snippet: import type { DropByServer } from "@dropby/server"; declare const dropby: DropByServer; -->
+
+```ts
+const { config } = await dropby.config.evaluate({
+  user: { id: "user_123", plan: "pro" },
+  account: { id: "acct_42" },
+});
+if (config.new_exports === true) {
+  // show the new exports
+}
+```
+
+It takes no `context` or `device`, so rules on them see those fields as missing:
+a condition that needs a value (`eq`, `in`, `exists`) never matches, and a
+negative one (`neq`, or `not` around another) always does. The server and the
+browser can therefore disagree for the same user. It needs a secret key with
+`config:read`.
+
+## Retries
+
+Every call retries by itself after a network error, a timeout, a 408, a 429 or
+a 5xx: twice by default, waiting up to half a second, then up to a second (set
+`maxRetries`, 0 to 10). A `Retry-After` of up to 10 seconds is waited out; a
+longer one ends the call at once, and the error's `retryAfter` says how long the
+API asked for. `timeoutMs` (30 seconds by default) bounds each attempt.
+
+Retrying is safe for every call. Updates and merges change nothing when
+repeated (though an update retried after a lost answer can overwrite a change
+a teammate made in between; updates are last-writer-wins), and `asks.create`, `chat.create`, `chat.reply` and `ideas.create` send
+an idempotency key, one per call, generated when you give none: a repeat returns
+what was created instead of posting again. If your backend retries a whole call
+itself, for example from a job queue, pass your own key so those attempts are
+one too:
+
+<!-- snippet: import type { DropByServer } from "@dropby/server"; declare const dropby: DropByServer; declare const threadId: string; declare const job: { replyId: string }; -->
+
+```ts
+// One key per write, stored with the job that retries it.
+await dropby.chat.reply(threadId, { text: "we're on it" }, { idempotencyKey: job.replyId });
+```
+
+- A key is 1 to 128 visible ASCII characters; use a UUID. Reusing one for a
+  different request is a 409 `idempotency_key_reused`.
+- An ask's and an idea's key are shared across your product and environment,
+  every secret key and the dashboard included. A reply's key is shared across
+  every secret key of the product and environment (the dashboard's replies keep
+  their own). A new thread's key is its first message's, scoped to the user and
+  account, and shared with that user's widget sends; the user's widget can see
+  it.
+- A repeat returns what was created as it is now: an ask may since be closed.
+  An ask is compared by what it asks and whom, so compute its window once and
+  keep it with the job; a recomputed `expiresAt` is a different request.
+- Keys never expire.
+
+## Errors
+
+Every error the client throws is a `DropByError` with a `code`, a `message`,
+the HTTP `status` (undefined when no response arrived), the `retryAfter` seconds
+when the API asked for a wait, and the underlying `cause`. An error that can pass
+is thrown once the retries are spent; any other at once:
+
+<!-- snippet: import type { DropByServer } from "@dropby/server"; declare const dropby: DropByServer; declare const threadId: string; declare const text: string; -->
+
+```ts
+import { DropByError } from "@dropby/server";
+
+try {
+  await dropby.chat.reply(threadId, { text });
+} catch (error) {
+  if (error instanceof DropByError && error.code === "rate_limited") {
+    // error.retryAfter says how long the API asked to wait
+  }
+  throw error;
+}
+```
+
+API codes are `bad_request`, `unauthorized`, `forbidden`, `not_found`,
+`conflict`, `idea_archived`, `idea_merged`, `idempotency_key_reused`,
+`rate_limited`, `unavailable` and `internal_error`; the API may add more. The
+client adds `invalid_input` (a bad argument or option, raised before anything
+is sent), `network_error`, `timeout` (30 seconds per attempt by default;
+set `timeoutMs`), `invalid_response` and `request_failed` (an error response without
+a DropBy error body). No message includes your keys.
+
+Responses are returned as the API sends them. New fields and values can appear
+as the API grows, so treat enums such as a status as open and keep a default
+branch when you switch over one.
+
+## Identity proofs
+
+`createIdentityProof` is an alternative server-side credential flow for a
+browser session endpoint. Sign it locally with your browser key's identity
+secret and return only the short-lived proof to the browser. Never use your
+secret key for this, and never send the identity secret to the browser.
+
+<!-- snippet: declare const user: { id: string; email?: string }; declare const account: { id: string; name?: string } | undefined; -->
+
+```ts
+import { createIdentityProof, identityProofOptionsFromEnv } from "@dropby/server";
+
+// Reads DROPBY_PRODUCT_ID, DROPBY_PUBLIC_KEY_ID, DROPBY_ENV and
+// DROPBY_IDENTITY_SECRET; throws at startup naming the first that is missing or invalid.
+const dropby = identityProofOptionsFromEnv(process.env);
+
+const identityProof = await createIdentityProof({
+  ...dropby,
+  user: { id: user.id, email: user.email },
+  ...(account ? { account: { id: account.id, name: account.name } } : {}),
+});
+// return { identityProof } from your authenticated session endpoint
+```
+
+On Cloudflare Workers, pass the request's `env` instead of `process.env`. Setting
+the four variables per environment lets one codebase serve test and live.
+
+Get these values from the dashboard: **settings → api keys**, then **reveal
+identity secret** on the browser key's actions menu (or from the identity proof
+option under "connect your app", whose server setup lists them). The dialog shows
+`DROPBY_PRODUCT_ID`, `DROPBY_PUBLIC_KEY_ID`, `DROPBY_ENV` and
+`DROPBY_IDENTITY_SECRET`. Only the secret is shown
+once. If you lose it, create a new browser key, update your backend and browser
+configuration, then revoke the old key.
+
+The proof carries only the user's `id`, `name`, `email` and `attributes` and the
+account's `id`, `name`, `domain` and `attributes`; other properties of the objects
+you pass are left out, since the browser can read the proof. Proofs expire within
+the supported short lifetime (900 seconds at most). The host backend remains the
+source of identity truth; request-body fields from the browser are not an
+authorization boundary.
+
+`createIdentityProof` checks the secret, ids and lifetime before signing. The API
+checks the rest (email, names, domain, attributes) when the browser exchanges
+the proof: a proof that breaks one of those rules is answered with a 400 naming
+the claim, such as `Invalid identity proof claims: user.email: …`.