@blinkdotnew/sdk 2.5.1 → 2.6.1

package/dist/index.d.mts

@@ -310,8 +310,8 @@ interface TableOperations<T = any> {
 declare class BlinkError extends Error {
     code?: string | undefined;
     status?: number | undefined;
-    details?: any;
-    constructor(message: string, code?: string | undefined, status?: number | undefined, details?: any);
+    details?: any | undefined;
+    constructor(message: string, code?: string | undefined, status?: number | undefined, details?: any | undefined);
 }
 interface StorageUploadOptions {
     /**
@@ -798,6 +798,32 @@ interface SendEmailRequest {
     subject: string;
     html?: string;
     text?: string;
+    /**
+     * Pick which sender this email goes out from.
+     *
+     * Two accepted shapes — the server disambiguates by whether the value
+     * contains an `@` character:
+     *   - **Full address** (any string containing `@`, e.g.
+     *     `"support@mail.acme.com"`) — sends from that specific verified
+     *     sender. The address must be set up in Settings → Email beforehand;
+     *     unverified addresses are rejected by the server with HTTP 403. On
+     *     the SDK side this surfaces as a `BlinkNotificationsError` whose
+     *     `.status === 403` and `.details?.code === 'UNVERIFIED_SENDER'` —
+     *     the SDK-level `.code` is always `'NOTIFICATIONS_ERROR'`, so branch
+     *     on `.status` + `.details` (not `.code`) to detect this case.
+     *   - **Display name** (any string without `@`, e.g. `"Acme Support"`) —
+     *     keeps the project's default sender address but overrides the
+     *     visible name in the recipient's inbox. Useful for tagging different
+     *     message types ("Acme Receipts", "Acme Updates") without verifying
+     *     more senders.
+     *
+     * A display name MUST NOT contain `@`. If it does, the server interprets
+     * it as a sending address and rejects with 403 `UNVERIFIED_SENDER`.
+     *
+     * Omit to use the project's default sender (the one flagged "Default"
+     * in Settings → Email — same one auth emails like password reset and
+     * magic links use).
+     */
     from?: string;
     replyTo?: string;
     cc?: string | string[];
@@ -915,7 +941,17 @@ declare class HttpClient {
     private readonly secretKey?;
     private getToken;
     private getValidToken?;
-    constructor(config: BlinkClientConfig, getToken: () => string | null, getValidToken?: () => Promise<string | null>);
+    private forceRefreshToken?;
+    constructor(config: BlinkClientConfig, getToken: () => string | null, getValidToken?: () => Promise<string | null>, forceRefreshToken?: () => Promise<string | null>);
+    /**
+     * Whether a 401 on this request is worth recovering from by forcing a
+     * user-token refresh and retrying once.
+     *
+     * Only meaningful for user-JWT auth: server-side `secretKey` 401s are real
+     * authorization failures a refresh cannot fix, and publishable-key requests
+     * carry no user token to refresh.
+     */
+    private canAttemptTokenRefresh;
     private shouldAttachPublishableKey;
     private shouldSkipSecretKey;
     private getAuthorizationHeader;
@@ -1007,17 +1043,17 @@ declare class HttpClient {
      * Stream AI text generation - uses Vercel AI SDK's pipeUIMessageStreamToResponse (Data Stream Protocol)
      */
     streamAiText(prompt: string, options: {
-        model?: string | undefined;
-        messages?: {
+        model?: string;
+        messages?: Array<{
             role: string;
             content: string | any[];
-        }[] | undefined;
-        search?: boolean | undefined;
-        maxSteps?: number | undefined;
-        experimental_continueSteps?: boolean | undefined;
-        maxTokens?: number | undefined;
-        temperature?: number | undefined;
-        signal?: AbortSignal | undefined;
+        }>;
+        search?: boolean;
+        maxSteps?: number;
+        experimental_continueSteps?: boolean;
+        maxTokens?: number;
+        temperature?: number;
+        signal?: AbortSignal;
     } | undefined, onChunk: (chunk: string) => void): Promise<any>;
     aiObject(prompt: string, options?: {
         model?: string;
@@ -1031,11 +1067,11 @@ declare class HttpClient {
      * Stream AI object generation - uses Vercel AI SDK's pipeTextStreamToResponse
      */
     streamAiObject(prompt: string, options: {
-        model?: string | undefined;
-        output?: "object" | "array" | "enum" | undefined;
+        model?: string;
+        output?: "object" | "array" | "enum";
         schema?: any;
-        enum?: string[] | undefined;
-        signal?: AbortSignal | undefined;
+        enum?: string[];
+        signal?: AbortSignal;
     } | undefined, onPartial: (partial: any) => void): Promise<any>;
     aiImage(prompt: string, options?: {
         model?: string;
@@ -1259,6 +1295,7 @@ declare class BlinkAuth {
     private initializationPromise;
     private isInitialized;
     private storage;
+    private refreshPromise;
     constructor(config: BlinkClientConfig);
     /**
      * Generate project-scoped storage key
@@ -1646,6 +1683,18 @@ declare class BlinkAuth {
      * Refresh access token using refresh token
      */
     refreshToken(): Promise<boolean>;
+    /**
+     * Force a server-side token refresh and return the resulting access token.
+     *
+     * Used by the HTTP client to recover from a 401 even when the client-side
+     * expiry heuristics believe the access token is still valid (clock skew, a
+     * restored session with a stale `issued_at`, or a refresh race). Delegates to
+     * {@link refreshToken} so it shares the single-flight guard.
+     *
+     * @returns The new access token, or null if refresh was not possible.
+     */
+    forceRefreshAccessToken(): Promise<string | null>;
+    private performTokenRefresh;
     /**
      * Add auth state change listener
      */

package/dist/index.d.ts

@@ -310,8 +310,8 @@ interface TableOperations<T = any> {
 declare class BlinkError extends Error {
     code?: string | undefined;
     status?: number | undefined;
-    details?: any;
-    constructor(message: string, code?: string | undefined, status?: number | undefined, details?: any);
+    details?: any | undefined;
+    constructor(message: string, code?: string | undefined, status?: number | undefined, details?: any | undefined);
 }
 interface StorageUploadOptions {
     /**
@@ -798,6 +798,32 @@ interface SendEmailRequest {
     subject: string;
     html?: string;
     text?: string;
+    /**
+     * Pick which sender this email goes out from.
+     *
+     * Two accepted shapes — the server disambiguates by whether the value
+     * contains an `@` character:
+     *   - **Full address** (any string containing `@`, e.g.
+     *     `"support@mail.acme.com"`) — sends from that specific verified
+     *     sender. The address must be set up in Settings → Email beforehand;
+     *     unverified addresses are rejected by the server with HTTP 403. On
+     *     the SDK side this surfaces as a `BlinkNotificationsError` whose
+     *     `.status === 403` and `.details?.code === 'UNVERIFIED_SENDER'` —
+     *     the SDK-level `.code` is always `'NOTIFICATIONS_ERROR'`, so branch
+     *     on `.status` + `.details` (not `.code`) to detect this case.
+     *   - **Display name** (any string without `@`, e.g. `"Acme Support"`) —
+     *     keeps the project's default sender address but overrides the
+     *     visible name in the recipient's inbox. Useful for tagging different
+     *     message types ("Acme Receipts", "Acme Updates") without verifying
+     *     more senders.
+     *
+     * A display name MUST NOT contain `@`. If it does, the server interprets
+     * it as a sending address and rejects with 403 `UNVERIFIED_SENDER`.
+     *
+     * Omit to use the project's default sender (the one flagged "Default"
+     * in Settings → Email — same one auth emails like password reset and
+     * magic links use).
+     */
     from?: string;
     replyTo?: string;
     cc?: string | string[];
@@ -915,7 +941,17 @@ declare class HttpClient {
     private readonly secretKey?;
     private getToken;
     private getValidToken?;
-    constructor(config: BlinkClientConfig, getToken: () => string | null, getValidToken?: () => Promise<string | null>);
+    private forceRefreshToken?;
+    constructor(config: BlinkClientConfig, getToken: () => string | null, getValidToken?: () => Promise<string | null>, forceRefreshToken?: () => Promise<string | null>);
+    /**
+     * Whether a 401 on this request is worth recovering from by forcing a
+     * user-token refresh and retrying once.
+     *
+     * Only meaningful for user-JWT auth: server-side `secretKey` 401s are real
+     * authorization failures a refresh cannot fix, and publishable-key requests
+     * carry no user token to refresh.
+     */
+    private canAttemptTokenRefresh;
     private shouldAttachPublishableKey;
     private shouldSkipSecretKey;
     private getAuthorizationHeader;
@@ -1007,17 +1043,17 @@ declare class HttpClient {
      * Stream AI text generation - uses Vercel AI SDK's pipeUIMessageStreamToResponse (Data Stream Protocol)
      */
     streamAiText(prompt: string, options: {
-        model?: string | undefined;
-        messages?: {
+        model?: string;
+        messages?: Array<{
             role: string;
             content: string | any[];
-        }[] | undefined;
-        search?: boolean | undefined;
-        maxSteps?: number | undefined;
-        experimental_continueSteps?: boolean | undefined;
-        maxTokens?: number | undefined;
-        temperature?: number | undefined;
-        signal?: AbortSignal | undefined;
+        }>;
+        search?: boolean;
+        maxSteps?: number;
+        experimental_continueSteps?: boolean;
+        maxTokens?: number;
+        temperature?: number;
+        signal?: AbortSignal;
     } | undefined, onChunk: (chunk: string) => void): Promise<any>;
     aiObject(prompt: string, options?: {
         model?: string;
@@ -1031,11 +1067,11 @@ declare class HttpClient {
      * Stream AI object generation - uses Vercel AI SDK's pipeTextStreamToResponse
      */
     streamAiObject(prompt: string, options: {
-        model?: string | undefined;
-        output?: "object" | "array" | "enum" | undefined;
+        model?: string;
+        output?: "object" | "array" | "enum";
         schema?: any;
-        enum?: string[] | undefined;
-        signal?: AbortSignal | undefined;
+        enum?: string[];
+        signal?: AbortSignal;
     } | undefined, onPartial: (partial: any) => void): Promise<any>;
     aiImage(prompt: string, options?: {
         model?: string;
@@ -1259,6 +1295,7 @@ declare class BlinkAuth {
     private initializationPromise;
     private isInitialized;
     private storage;
+    private refreshPromise;
     constructor(config: BlinkClientConfig);
     /**
      * Generate project-scoped storage key
@@ -1646,6 +1683,18 @@ declare class BlinkAuth {
      * Refresh access token using refresh token
      */
     refreshToken(): Promise<boolean>;
+    /**
+     * Force a server-side token refresh and return the resulting access token.
+     *
+     * Used by the HTTP client to recover from a 401 even when the client-side
+     * expiry heuristics believe the access token is still valid (clock skew, a
+     * restored session with a stale `issued_at`, or a refresh race). Delegates to
+     * {@link refreshToken} so it shares the single-flight guard.
+     *
+     * @returns The new access token, or null if refresh was not possible.
+     */
+    forceRefreshAccessToken(): Promise<string | null>;
+    private performTokenRefresh;
     /**
      * Add auth state change listener
      */