@ragable/sdk 0.6.24 → 0.7.5

package/dist/index.d.mts

@@ -74,20 +74,10 @@ type ColumnValue<D extends RagableDatabase, T extends RagableTableNames<D>, C ex
  * or the browser throws **Illegal invocation**. Use this for defaults and for `options.fetch`.
  */
 declare function bindFetch(custom?: typeof fetch): typeof fetch;
-/** Default hosted Ragable HTTP API base (`…/api`) when **`baseUrl`** is omitted. */
+/** Hosted Ragable HTTP API base (`…/api`) — used by all SDK clients (not configurable). */
 declare const DEFAULT_RAGABLE_API_BASE = "https://ragable-341305259977.asia-southeast1.run.app/api";
-/**
- * Normalize the API base (no trailing slash). Use **`DEFAULT_RAGABLE_API_BASE`** when
- * **`explicitBaseUrl`** is missing or blank.
- */
-declare function resolveRagableApiBase(explicitBaseUrl?: string | null | undefined): string;
 interface RagableClientOptions {
     apiKey: string;
-    /**
-     * HTTP API root including the **`/api`** segment, e.g. `https://your-host.com/api`.
-     * Defaults to {@link DEFAULT_RAGABLE_API_BASE}.
-     */
-    baseUrl?: string;
     fetch?: typeof fetch;
     headers?: HeadersInit;
 }
@@ -904,8 +894,6 @@ interface AuthOptions {
 }
 interface RagableAuthConfig {
     authGroupId: string;
-    /** HTTP API root (including `/api`); set from the browser client **`baseUrl`** option. */
-    baseUrl?: string;
     fetch?: typeof fetch;
     headers?: HeadersInit;
     auth?: AuthOptions;
@@ -1110,11 +1098,8 @@ declare class Transport {
 }
 declare function parseTransportResponse<T>(response: Response): Promise<T>;
 
-/**
- * Resolved API base (`…/api`, no trailing slash). With no argument, uses the same default as
- * {@link resolveRagableApiBase}.
- */
-declare function normalizeBrowserApiBase(explicitBaseUrl?: string): string;
+/** Canonical browser/server API base (`…/api`, no trailing slash). */
+declare function normalizeBrowserApiBase(): string;
 type BrowserDataAuthMode = "user" | "publicAnon" | "admin";
 /**
  * Resolves how database requests are authorized. If `dataAuth` is omitted and a
@@ -1126,12 +1111,6 @@ type BrowserDataAuthMode = "user" | "publicAnon" | "admin";
 declare function effectiveDataAuth(options: RagableBrowserClientOptions): BrowserDataAuthMode;
 interface RagableBrowserClientOptions {
     organizationId: string;
-    /**
-     * HTTP API root including **`/api`**, e.g. `https://your-host.com/api` or
-     * `import.meta.env.VITE_RAGABLE_API_BASE`. Trailing slashes are stripped.
-     * When omitted, the package default **`DEFAULT_RAGABLE_API_BASE`** is used.
-     */
-    baseUrl?: string;
     websiteId?: string;
     authGroupId?: string;
     databaseInstanceId?: string;
@@ -1439,7 +1418,6 @@ declare class RagableBrowserDatabaseClient<Database extends RagableDatabase = De
     private readonly options;
     private readonly ragableAuth;
     private readonly fetchImpl;
-    private readonly apiBase;
     private _transport;
     readonly collections: BrowserCollections<Database>;
     readonly collection: BrowserCollectionFactory<Database>;
@@ -1563,7 +1541,6 @@ interface AgentConversationSubscription {
 declare class RagableBrowserAgentsClient {
     private readonly options;
     private readonly fetchImpl;
-    private readonly apiBase;
     constructor(options: RagableBrowserClientOptions);
     private toUrl;
     private requireWebsiteId;
@@ -1684,9 +1661,308 @@ declare function formatRetrievalContext(results: ShiftSearchResult[], options?:
  */
 declare function createRagPipeline(client: RagClientForPipeline, options: RagPipelineOptions): RagPipeline;
 
+interface StorageBucket {
+    id: string;
+    name: string;
+    organizationId: string;
+    status: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface StorageBucketItem {
+    type: "file" | "folder";
+    path: string;
+    name: string;
+    /** File size in bytes (files only). */
+    size?: string | null;
+    contentType?: string | null;
+    updated?: string | null;
+    generation?: string | null;
+}
+interface StorageListContentsResult {
+    bucket: string;
+    prefix: string;
+    items: StorageBucketItem[];
+    nextPageToken: string | null;
+}
+interface StorageListBucketsParams {
+    /** Filter by name substring. */
+    q?: string;
+    status?: string;
+    sort?: string;
+}
+interface StorageListContentsParams {
+    /** Folder prefix to list inside (e.g. `"reports/"`). */
+    prefix?: string;
+    /** Path delimiter — defaults to `"/"` on the server. */
+    delimiter?: string;
+    maxResults?: number;
+    pageToken?: string;
+}
+type StorageUploadableFile = Blob | ArrayBuffer | Uint8Array;
+interface StorageUploadParams {
+    /** Target path inside the bucket (e.g. `"reports/jan.pdf"`). */
+    objectPath: string;
+    file: StorageUploadableFile;
+    /** Optional filename hint for content-type detection. */
+    fileName?: string;
+    contentType?: string;
+    /** HTTP `Cache-Control` header stored with the object. */
+    cacheControl?: string;
+}
+interface StorageUploadResult {
+    success: true;
+    path: string;
+    size: string | null;
+    contentType: string | null;
+    generation: string | null;
+    updated: string | null;
+}
+interface StorageDownloadParams {
+    objectPath: string;
+    /** When `true`, the response includes `text` if the file fits in `maxTextBytes`. */
+    asText?: boolean;
+    /** Maximum bytes to decode as text (default 1 MB, max 5 MB). */
+    maxTextBytes?: number;
+}
+interface StorageDownloadResult {
+    path: string;
+    size: string | null;
+    contentType: string | null;
+    updated: string | null;
+    generation: string | null;
+    /** Always `"base64"`. */
+    encoding: string;
+    /** Full file contents encoded as base64. */
+    contentsBase64: string;
+    /** UTF-8 decoded text when `asText: true` and size ≤ `maxTextBytes`. */
+    text: string | null;
+    textIncluded: boolean;
+}
+interface StorageObjectMetadata {
+    name: string;
+    bucket: string;
+    contentType: string | null;
+    size: string | null;
+    updated: string | null;
+    generation: string | null;
+    metadata?: Record<string, string>;
+    [key: string]: unknown;
+}
+interface StorageUpdateMetadataParams {
+    objectPath: string;
+    contentType?: string;
+    cacheControl?: string;
+    metadata?: Record<string, string>;
+}
+interface StorageCopyMoveParams {
+    sourcePath: string;
+    destinationPath: string;
+}
+interface StorageBulkDeleteResult {
+    success: boolean;
+    totalRequested: number;
+    uniquePaths: number;
+    deleted: string[];
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+interface StorageSignedUploadUrlParams {
+    objectPath: string;
+    /** Expiry in seconds — clamped to [60, 3600] by the server. Default 900. */
+    expiresInSeconds?: number;
+    contentType?: string;
+}
+interface StorageSignedUploadUrlResult {
+    url: string;
+    method: string;
+    expiresInSeconds: number;
+    objectPath: string;
+}
+interface StorageSignedDownloadUrlParams {
+    objectPath: string;
+    /** Expiry in seconds — clamped to [60, 86400] by the server. Default 900. */
+    expiresInSeconds?: number;
+}
+interface StorageSignedDownloadUrlResult {
+    url: string;
+    method: string;
+    expiresInSeconds: number;
+    objectPath: string;
+}
+interface StorageBucketCorsEntry {
+    origin?: string[];
+    method?: string[];
+    responseHeader?: string[];
+    maxAgeSeconds?: number;
+}
+interface StorageBucketSettings {
+    id: string;
+    logicalName: string;
+    gcpBucketName: string;
+    location: string | null;
+    storageClass: string | null;
+    labels: Record<string, string>;
+    versioningEnabled: boolean;
+    publicAccessPrevention: string | null;
+    uniformBucketLevelAccessEnabled: boolean;
+    cors: StorageBucketCorsEntry[];
+    retentionPolicy: unknown;
+    lifecycleRules: unknown[];
+    updated: string | null;
+}
+interface StorageUpdateBucketSettingsParams {
+    labels?: Record<string, string>;
+    storageClass?: string;
+    versioningEnabled?: boolean;
+    publicAccessPrevention?: "inherited" | "enforced";
+    uniformBucketLevelAccessEnabled?: boolean;
+    cors?: StorageBucketCorsEntry[];
+}
+/**
+ * Object/file operations scoped to a single bucket.
+ * Obtained via {@link StorageClient.from}.
+ *
+ * @example
+ * const bucket = ragable.storage.from("bucket-id");
+ *
+ * // Upload a file
+ * await bucket.upload({ objectPath: "data/report.pdf", file: pdfBlob });
+ *
+ * // Download and read as text
+ * const { text } = await bucket.download({ objectPath: "data/notes.txt", asText: true });
+ *
+ * // Generate a short-lived public download link
+ * const { url } = await bucket.getSignedDownloadUrl({ objectPath: "data/report.pdf" });
+ */
+interface StorageBucketClient {
+    /** List objects and sub-folders inside this bucket (optionally under a prefix). */
+    list(params?: StorageListContentsParams): Promise<StorageListContentsResult>;
+    /** Create an empty folder placeholder (GCS folder marker). */
+    createFolder(folderPath: string): Promise<{
+        success: true;
+        folderPath: string;
+    }>;
+    /** Delete a folder and all objects under it. */
+    deleteFolder(folderPath: string): Promise<{
+        success: true;
+        folderPath: string;
+    }>;
+    /** Upload a file to the specified `objectPath`. */
+    upload(params: StorageUploadParams): Promise<StorageUploadResult>;
+    /** Delete a single object. */
+    delete(objectPath: string): Promise<{
+        success: true;
+        path: string;
+    }>;
+    /** Delete up to 1 000 objects in one call. */
+    bulkDelete(objectPaths: string[]): Promise<StorageBulkDeleteResult>;
+    /** Retrieve GCS metadata for an object. */
+    getMetadata(objectPath: string): Promise<StorageObjectMetadata>;
+    /** Update `contentType`, `cacheControl`, or custom `metadata` for an object. */
+    updateMetadata(params: StorageUpdateMetadataParams): Promise<StorageObjectMetadata>;
+    /**
+     * Download an object. Contents are always returned as `contentsBase64`.
+     * Pass `asText: true` to also receive a decoded `text` field (≤ maxTextBytes).
+     */
+    download(params: StorageDownloadParams): Promise<StorageDownloadResult>;
+    /** Copy an object to a new path inside the same bucket. */
+    copy(params: StorageCopyMoveParams): Promise<{
+        success: true;
+        sourcePath: string;
+        destinationPath: string;
+    }>;
+    /** Move (rename) an object inside the same bucket. */
+    move(params: StorageCopyMoveParams): Promise<{
+        success: true;
+        sourcePath: string;
+        destinationPath: string;
+    }>;
+    /**
+     * Generate a signed URL for direct client-side PUT upload (bypasses your server).
+     * Use this when a website needs to upload large files directly to GCS.
+     */
+    getSignedUploadUrl(params: StorageSignedUploadUrlParams): Promise<StorageSignedUploadUrlResult>;
+    /**
+     * Generate a signed URL for direct client-side download.
+     * Useful for serving private files without proxying through your server.
+     */
+    getSignedDownloadUrl(params: StorageSignedDownloadUrlParams): Promise<StorageSignedDownloadUrlResult>;
+    /** Retrieve GCS-level settings for this bucket (CORS, versioning, storage class …). */
+    getSettings(): Promise<StorageBucketSettings>;
+    /** Update GCS-level settings for this bucket. */
+    updateSettings(params: StorageUpdateBucketSettingsParams): Promise<StorageBucketSettings>;
+}
+/**
+ * Server-side storage client — access via `ragable.storage`.
+ *
+ * Manages GCS-backed storage buckets for your organisation and exposes typed
+ * helpers for every object-storage operation websites need for durable storage.
+ *
+ * ```ts
+ * import { createClient } from "@ragable/sdk";
+ *
+ * const ragable = createClient({ apiKey: process.env.RAGABLE_API_KEY! });
+ *
+ * // ── Bucket management ───────────────────────────────────────────────────
+ * const buckets = await ragable.storage.buckets.list();
+ * const bucket  = await ragable.storage.buckets.create("my-website-assets");
+ *
+ * // ── Object operations (via .from()) ─────────────────────────────────────
+ * const b = ragable.storage.from(bucket.id);
+ *
+ * await b.upload({ objectPath: "pages/index.html", file: htmlBlob, contentType: "text/html" });
+ * const { text } = await b.download({ objectPath: "pages/index.html", asText: true });
+ *
+ * // ── Signed URLs for client-side direct upload/download ──────────────────
+ * const { url } = await b.getSignedUploadUrl({ objectPath: "uploads/photo.jpg", contentType: "image/jpeg" });
+ * ```
+ */
+declare class StorageClient {
+    private readonly client;
+    /**
+     * Bucket-level CRUD — list, create and delete buckets for this organisation.
+     */
+    readonly buckets: {
+        /**
+         * List all managed storage buckets.
+         *
+         * @param params Optional filter / sort params (`q`, `status`, `sort`).
+         */
+        list(params?: StorageListBucketsParams): Promise<StorageBucket[]>;
+        /**
+         * Create a new managed GCS bucket.
+         *
+         * The `name` must be lowercase alphanumeric + dashes, max 63 chars.
+         */
+        create(name: string): Promise<StorageBucket>;
+        /**
+         * Permanently delete a bucket and **all** its contents.
+         *
+         * @param bucketId The Ragable bucket ID (not the raw GCS bucket name).
+         */
+        delete(bucketId: string): Promise<{
+            success: true;
+        }>;
+    };
+    constructor(client: RagableRequestClient);
+    /**
+     * Returns a {@link StorageBucketClient} scoped to the given bucket ID.
+     *
+     * All object operations (upload, download, list, copy, move, signed URLs, …)
+     * are performed through the returned client.
+     *
+     * @param bucketId The Ragable bucket ID obtained from `buckets.list()` or `buckets.create()`.
+     */
+    from(bucketId: string): StorageBucketClient;
+}
+
 declare class Ragable {
     readonly shift: ShiftClient;
     readonly agents: AgentsClient;
+    readonly storage: StorageClient;
     readonly infrastructure: {
         shift: ShiftClient;
     };
@@ -1696,4 +1972,4 @@ declare function createClient(options: RagableClientOptions): Ragable;
 declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
 declare function createRagableServerClient(options: RagableClientOptions): Ragable;
 
-export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentChatStreamDonePayload, type AgentChatStreamHandlers, type AgentChatStreamResult, type AgentChatStreamUiHandlers, type AgentChatUiAssistantMessage, type AgentChatUiSegment, type AgentChatUiStreamResult, type AgentConversation, type AgentConversationMessage, type AgentConversationSubscription, type AgentPublicChatParams, type AgentStreamAgentInfoEvent, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type AuthSignUpCredentials, type AuthUpdateUserAttributes, type AuthUserMetadata, type BrowserAuthSession, type BrowserAuthTokens, BrowserCollectionApi, type BrowserCollectionDefinition, type BrowserCollectionFactory, type BrowserCollectionFindParams, type BrowserCollectionRecord, type BrowserCollections, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type CollectionReturnMode, type CollectionRowData, type CollectionRowWithMeta, type CollectionWhere, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultAuthUser, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, type RagableResult, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunAgentChatStreamOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, type WhereInput, type WhereOperatorObject, asPostgrestResponse, assertPostgrestSuccess, bindFetch, collectAssistantTextFromUiSegments, collectionRecordToRowWithMeta, collectionRecordsToRowWithMeta, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, effectiveDataAuth, extractErrorMessage, finalizeAgentChatUiTurn, foldAgentStreamIntoUiSegments, formatPostgrestError, formatRetrievalContext, formatSdkError, generateIdempotencyKey, isIncompleteAgentStreamError, normalizeBrowserApiBase, parseAgentStreamAgentInfo, parseAgentStreamDone, parseSseDataLine, parseTransportResponse, readSseStream, resolveRagableApiBase, runAgentChatStream, runAgentChatStreamForUi, runAgentChatStreamLenient, toRagableResult, unwrapPostgrest };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentChatStreamDonePayload, type AgentChatStreamHandlers, type AgentChatStreamResult, type AgentChatStreamUiHandlers, type AgentChatUiAssistantMessage, type AgentChatUiSegment, type AgentChatUiStreamResult, type AgentConversation, type AgentConversationMessage, type AgentConversationSubscription, type AgentPublicChatParams, type AgentStreamAgentInfoEvent, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type AuthSignUpCredentials, type AuthUpdateUserAttributes, type AuthUserMetadata, type BrowserAuthSession, type BrowserAuthTokens, BrowserCollectionApi, type BrowserCollectionDefinition, type BrowserCollectionFactory, type BrowserCollectionFindParams, type BrowserCollectionRecord, type BrowserCollections, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type CollectionReturnMode, type CollectionRowData, type CollectionRowWithMeta, type CollectionWhere, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultAuthUser, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, type RagableResult, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunAgentChatStreamOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type StorageBucket, type StorageBucketClient, type StorageBucketCorsEntry, type StorageBucketItem, type StorageBucketSettings, type StorageBulkDeleteResult, StorageClient, type StorageCopyMoveParams, type StorageDownloadParams, type StorageDownloadResult, type StorageListBucketsParams, type StorageListContentsParams, type StorageListContentsResult, type StorageObjectMetadata, type StorageSignedDownloadUrlParams, type StorageSignedDownloadUrlResult, type StorageSignedUploadUrlParams, type StorageSignedUploadUrlResult, type StorageUpdateBucketSettingsParams, type StorageUpdateMetadataParams, type StorageUploadParams, type StorageUploadResult, type StorageUploadableFile, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, type WhereInput, type WhereOperatorObject, asPostgrestResponse, assertPostgrestSuccess, bindFetch, collectAssistantTextFromUiSegments, collectionRecordToRowWithMeta, collectionRecordsToRowWithMeta, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, effectiveDataAuth, extractErrorMessage, finalizeAgentChatUiTurn, foldAgentStreamIntoUiSegments, formatPostgrestError, formatRetrievalContext, formatSdkError, generateIdempotencyKey, isIncompleteAgentStreamError, normalizeBrowserApiBase, parseAgentStreamAgentInfo, parseAgentStreamDone, parseSseDataLine, parseTransportResponse, readSseStream, runAgentChatStream, runAgentChatStreamForUi, runAgentChatStreamLenient, toRagableResult, unwrapPostgrest };