@sublay/js 5.0.0 → 7.0.0

package/README.md

@@ -5,9 +5,7 @@
 
 > **Backend infrastructure for user-powered products.** Pre-modeled bundles for the layers every app ends up rebuilding — comments, notifications, files, search, chat, and more. Install what you need, call through one SDK. Build the part that's actually yours.
 
-Framework-agnostic JavaScript SDK for Sublay. For browser apps and JS runtimes that don't use React, or don't want the React provider tree.
-
-Exposes a single `SublayClient` with module namespaces for `users`, `entities`, and `comments`.
+Framework-agnostic JavaScript SDK for Sublay. For browser apps and JS runtimes that don't use React, or don't want the React provider tree. It mirrors the Sublay v7 API surface — authenticated as an end user via a bearer token — without any React or state-management dependencies.
 
 ```bash
 npm install @sublay/js
@@ -16,13 +14,44 @@ npm install @sublay/js
 ```ts
 import { SublayClient } from "@sublay/js";
 
+// SDK-managed auth: the SDK holds the tokens and auto-refreshes them on expiry.
 const sublay = await SublayClient.init({
   projectId: "your-project-id",
+  onAuthChange: (tokens) => {
+    // Persist tokens so the session survives a reload (called with null on sign-out).
+  },
 });
 
-const entities = await sublay.entities.list({ ... });
+await sublay.auth.signIn({ email, password });
+
+const { entities } = await sublay.entities.fetchManyEntities({
+  sortBy: "hot",
+  limit: 20,
+});
 ```
 
+**Two auth modes.** By default the SDK is *SDK-managed*: it stores the tokens in memory, attaches the bearer on every request, auto-refreshes on a 403, and fires `onAuthChange` so you can persist them. If your host app already owns the token (e.g. it's shared with another SDK), pass `getToken` to `init({ ... })` for *host-managed* mode — the SDK then reads the token from your hook on each request and never stores or refreshes it itself.
+
+### API surface
+
+One `SublayClient` with 14 module namespaces (call them as `sublay.<module>.<fn>(...)`):
+
+| Namespace | What it covers |
+| --- | --- |
+| `auth` | sign up / in / out, email verification, password reset, token refresh |
+| `users` | profiles, username lookup, suggestions, updates, and the per-user follow/connection graph |
+| `entities` | content CRUD, drafts, feeds (`fetchManyEntities`), reactions, saves |
+| `comments` | threaded comments CRUD, reactions |
+| `spaces` | communities: lifecycle, membership, roles, rules, digests, moderation |
+| `collections` | saved-entity collections |
+| `follows` / `connections` | the logged-in user's own follow graph and mutual connections |
+| `appNotifications` | in-app notifications and unread counts |
+| `reports` | submit reports, fetch the moderation queue |
+| `search` | semantic `searchContent` / `searchUsers` / `searchSpaces`, plus streaming `askContent` |
+| `storage` | file & image uploads, fetch, delete |
+| `oauth` | OAuth sign-in/link (redirect flow) and identity management |
+| `chat` | conversations, members, messages, reactions, read-state, reporting |
+
 See [docs.sublay.io](https://docs.sublay.io) for the full reference.
 
 ---

package/dist/core/client.d.ts

@@ -1,8 +1,64 @@
 import { AxiosInstance } from "axios";
+export interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+}
 export interface ClientConfig {
     projectId: string;
+    /**
+     * Optional tokens to hydrate the SDK on init (SDK-managed mode) — e.g. tokens
+     * the host app persisted from a previous session.
+     */
+    initialTokens?: AuthTokens;
+    /**
+     * Optional async hook returning the current access token. **Providing it puts
+     * the SDK in "host-managed" mode**: the host owns the token and its refresh,
+     * and the SDK never stores or refreshes tokens itself.
+     */
+    getToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * Called whenever the SDK sets, rotates, or clears tokens (SDK-managed mode
+     * only). Receives `null` on sign-out. Use it to persist tokens so a session
+     * survives a reload.
+     */
+    onAuthChange?: (tokens: AuthTokens | null) => void;
 }
 export declare class SublayHttpClient {
-    instance: AxiosInstance;
-    constructor({ projectId }: ClientConfig);
+    projectInstance: AxiosInstance;
+    private readonly baseURL;
+    private readonly hostManaged;
+    private readonly getToken?;
+    private readonly onAuthChange?;
+    private accessToken;
+    private refreshToken;
+    /** Shared so concurrent 403s trigger a single refresh (mutex). */
+    private refreshPromise;
+    constructor({ projectId, initialTokens, getToken, onAuthChange, }: ClientConfig);
+    /**
+     * The SDK's own in-memory access token (SDK-managed mode). Distinct from the
+     * `init({ getToken })` host hook, which supplies a token in host-managed mode.
+     */
+    getAccessToken(): string | null;
+    getRefreshToken(): string | null;
+    /**
+     * The `Authorization` header value (`Bearer <token>`) for the active auth
+     * mode, or `undefined` if there is no token. Host-managed mode reads the
+     * `getToken` hook; SDK-managed mode reads the in-memory access token. Use this
+     * for requests that bypass `projectInstance` (e.g. the SSE `askContent`
+     * stream, which needs `fetch` rather than axios).
+     */
+    getAuthHeader(): Promise<string | undefined>;
+    /** Store a full token pair (SDK-managed mode only; no-op when host-managed). */
+    setTokens(tokens: AuthTokens): void;
+    /** Update just the access token, e.g. after a refresh (no-op when host-managed). */
+    setAccessToken(accessToken: string): void;
+    /** Clear tokens and notify with null (SDK-managed mode only). */
+    clearTokens(): void;
+    /**
+     * Refresh the access token using the in-memory refresh token. A single shared
+     * promise (mutex) means concurrent 403s trigger only one network refresh. The
+     * call goes through a bare axios (not `projectInstance`) so it never re-enters
+     * the response interceptor. Returns the new access token, or null on failure.
+     */
+    private refreshAccessToken;
 }

package/dist/core/multipart.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Helpers for building `multipart/form-data` request bodies. Shared by every
+ * upload site (storage, chat messages, user avatar/banner) so they encode
+ * fields identically: object/array values are JSON-stringified (the server
+ * re-parses them), scalars are coerced to strings, and `undefined` is skipped.
+ *
+ * Do NOT set the request's `Content-Type` manually for these bodies — axios sets
+ * it to `undefined` for a `FormData` instance so the browser writes the
+ * multipart boundary itself.
+ */
+/** Append a single field: skip `undefined`, JSON-stringify objects/arrays. */
+export declare function appendField(form: FormData, key: string, value: unknown): void;
+/** Append every own field of `fields` via {@link appendField}. */
+export declare function appendFields(form: FormData, fields: Record<string, unknown>): void;
+/**
+ * Append a file part under `field`. The multipart filename is, in order of
+ * precedence: an explicit `filename`, the `File`'s own name, then `fallback`.
+ */
+export declare function appendFile(form: FormData, field: string, file: Blob | File, opts?: {
+    filename?: string;
+    fallback?: string;
+}): void;