@react-native-firebase/storage 24.1.1 → 25.0.0

package/lib/types/internal.ts

@@ -0,0 +1,189 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import type { ModuleConfig } from '@react-native-firebase/app/dist/module/types/internal';
+import type {
+  FirebaseStorage,
+  StorageReference,
+  EmulatorMockTokenOptions,
+  SettableMetadata,
+  UploadMetadata,
+  Task,
+  TaskSnapshot,
+  FullMetadata,
+  ListResult,
+  ListOptions,
+} from './storage';
+import type EventEmitter from 'react-native/Libraries/vendor/emitter/EventEmitter';
+
+/**
+ * Internal Storage type with access to private properties.
+ * Used internally by StorageReference and other internal classes.
+ */
+export type StorageInternal = FirebaseStorage & {
+  native: RNFBStorageModule;
+  _customUrlOrRegion: string | null;
+  emitter: EventEmitter;
+  eventNameForApp: (...args: Array<string | number>) => string;
+  _config: ModuleConfig;
+  /**
+   * Returns a reference to the object at the specified path.
+   *
+   * @param path - An optional string pointing to a location on the storage bucket. If no path
+   * is provided, the returned reference will be the bucket root path.
+   */
+  ref(path?: string): StorageReference;
+
+  /**
+   * Returns a reference to the object at the specified URL.
+   *
+   * @param url - A storage bucket URL pointing to a single file or location. Must be either a `gs://` url or an `http` url.
+   */
+  refFromURL(url: string): StorageReference;
+
+  /**
+   * Sets the maximum time in milliseconds to retry operations if a failure occurs.
+   *
+   * @param time - The new maximum operation retry time in milliseconds.
+   */
+  setMaxOperationRetryTime(time: number): Promise<void>;
+
+  /**
+   * Sets the maximum time in milliseconds to retry an upload if a failure occurs.
+   *
+   * @param time - The new maximum upload retry time in milliseconds.
+   */
+  setMaxUploadRetryTime(time: number): Promise<void>;
+
+  /**
+   * Sets the maximum time in milliseconds to retry a download if a failure occurs.
+   *
+   * @param time - The new maximum download retry time in milliseconds.
+   */
+  setMaxDownloadRetryTime(time: number): Promise<void>;
+
+  /**
+   * Changes this instance to point to a Cloud Storage emulator running locally.
+   *
+   * @param host - The host of the emulator, e.g. "localhost" or "10.0.2.2" for Android.
+   * @param port - The port of the emulator, e.g. 9199.
+   * @param options - Optional settings for the emulator connection (web only).
+   * @returns {void} - Undocumented return, just used to unit test android host remapping.
+   */
+  useEmulator(host: string, port: number, options?: EmulatorMockTokenOptions): void;
+};
+
+/**
+ * Internal Reference type with access to private properties.
+ * Used internally by StorageTask and other internal classes.
+ */
+export type StorageReferenceInternal = StorageReference & {
+  _storage: StorageInternal;
+  child(path: string): StorageReference;
+  delete(): Promise<void>;
+  getDownloadURL(): Promise<string>;
+  getMetadata(): Promise<FullMetadata>;
+  list(options?: ListOptions): Promise<ListResult>;
+  listAll(): Promise<ListResult>;
+  put(data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): Task;
+  putString(
+    string: string,
+    format?: 'raw' | 'base64' | 'base64url' | 'data_url',
+    metadata?: UploadMetadata,
+  ): Task;
+  updateMetadata(metadata: SettableMetadata): Promise<FullMetadata>;
+  writeToFile(filePath: string): Task;
+  putFile(filePath: string, metadata?: UploadMetadata): Task;
+};
+
+/**
+ * Internal ListResult type with access to private properties.
+ * Used internally by StorageListResult and other internal classes.
+ */
+export type ListResultInternal = {
+  nextPageToken?: string | null;
+  items: string[];
+  prefixes: string[];
+};
+
+/**
+ * Wrapped native module interface for Storage.
+ *
+ * Note: React Native Firebase internally wraps native methods and auto-prepends the app name
+ * when `hasMultiAppSupport` is enabled. This interface represents the *wrapped* module shape
+ * that is exposed as `this.native` within FirebaseModule subclasses.
+ */
+export interface RNFBStorageModule {
+  /**
+   * Native constants exposed on the module.
+   * These are read during module construction to seed the JS-side values.
+   */
+  maxUploadRetryTime?: number;
+  maxDownloadRetryTime?: number;
+  maxOperationRetryTime?: number;
+
+  setMaxOperationRetryTime(time: number): Promise<void>;
+  setMaxUploadRetryTime(time: number): Promise<void>;
+  setMaxDownloadRetryTime(time: number): Promise<void>;
+
+  delete(url: string): Promise<void>;
+  getDownloadURL(url: string): Promise<string>;
+  getMetadata(url: string): Promise<FullMetadata>;
+  updateMetadata(url: string, metadata: SettableMetadata): Promise<FullMetadata>;
+
+  list(
+    url: string,
+    options: { maxResults: number; pageToken?: string },
+  ): Promise<ListResultInternal>;
+  listAll(url: string): Promise<ListResultInternal>;
+
+  putString(
+    url: string,
+    data: string,
+    format: string,
+    metadata: UploadMetadata | undefined,
+    taskId: number,
+  ): Promise<TaskSnapshot>;
+  putFile(
+    url: string,
+    filePath: string,
+    metadata: UploadMetadata | undefined,
+    taskId: number,
+  ): Promise<TaskSnapshot>;
+  writeToFile(url: string, filePath: string, taskId: number): Promise<TaskSnapshot>;
+
+  /**
+   * Set a running task status.
+   * - 0: pause
+   * - 1: resume
+   * - 2: cancel
+   */
+  setTaskStatus(taskId: number, status: number): Promise<boolean>;
+
+  /**
+   * Configure storage emulator.
+   *
+   * iOS does not persist emulator state between calls, so JS sends bucket/customUrlOrRegion through.
+   */
+  useEmulator(host: string, port: number, customUrlOrRegion?: string | null): void;
+}
+
+declare module '@react-native-firebase/app/dist/module/internal/NativeModules' {
+  interface ReactNativeFirebaseNativeModules {
+    RNFBStorageModule: RNFBStorageModule;
+  }
+}

package/lib/{index.d.ts → types/namespaced.ts}

@@ -15,7 +15,7 @@
  *
  */
 
-import { ReactNativeFirebase } from '@react-native-firebase/app';
+import type { ReactNativeFirebase } from '@react-native-firebase/app';
 
 /**
  * Firebase Cloud Storage package for React Native.
@@ -53,13 +53,20 @@ import { ReactNativeFirebase } from '@react-native-firebase/app';
  *
  * @firebase storage
  */
+/**
+ * @deprecated Use the exported types directly instead.
+ * FirebaseStorageTypes namespace is kept for backwards compatibility.
+ */
+/* eslint-disable @typescript-eslint/no-namespace */
 export namespace FirebaseStorageTypes {
-  import FirebaseModule = ReactNativeFirebase.FirebaseModule;
-  import NativeFirebaseError = ReactNativeFirebase.NativeFirebaseError;
+  type FirebaseModule = ReactNativeFirebase.FirebaseModule;
+  type NativeFirebaseError = ReactNativeFirebase.NativeFirebaseError;
 
   /**
    * Possible string formats used for uploading via `StorageReference.putString()`
    *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
+   *
    * ```js
    * firebase.storage.StringFormat;
    * ```
@@ -143,19 +150,26 @@ export namespace FirebaseStorageTypes {
    *
    * Event subscription is created via `StorageTask.on()`.
    *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
+   *
    * ```js
    * firebase.storage.TaskEvent;
    * ```
    */
-  export interface TaskEvent {
-    /**
-     * An event that indicates that the tasks state has changed.
-     *
-     * ```js
-     * firebase.storage.TaskEvent.STATE_CHANGED;
-     * ```
-     */
-    STATE_CHANGED: 'state_changed';
+  /**
+   * An event that is triggered on a task.
+   *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
+   */
+  export type TaskEvent = 'state_changed';
+
+  /**
+   * Static properties for task events (runtime object).
+   *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
+   */
+  export interface TaskEventStatic {
+    STATE_CHANGED: TaskEvent;
   }
 
   /**
@@ -163,6 +177,8 @@ export namespace FirebaseStorageTypes {
    *
    * An event subscription is created via `StorageTask.on()`.
    *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
+   *
    * ```js
    * firebase.storage.TaskEvent;
    * ```
@@ -171,7 +187,7 @@ export namespace FirebaseStorageTypes {
     /**
      * Task has been cancelled by the user.
      */
-    CANCELLED: 'cancelled';
+    CANCELLED: 'canceled';
 
     /**
      * An Error occurred, see TaskSnapshot.error for details.
@@ -194,9 +210,20 @@ export namespace FirebaseStorageTypes {
     SUCCESS: 'success';
   }
 
+  /**
+   * Represents the current state of a running upload.
+   *
+   * Note: The Firebase JS SDK uses "canceled" (one L). React Native Firebase historically used "cancelled" (two L).
+   *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
+   */
+  export type TaskStateType = 'running' | 'paused' | 'success' | 'canceled' | 'error';
+
   /**
    * Cloud Storage statics.
    *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
+   *
    * #### Example
    *
    * ```js
@@ -235,14 +262,16 @@ export namespace FirebaseStorageTypes {
      * firebase.storage.TaskEvent;
      * ```
      */
-    TaskEvent: TaskEvent;
+    TaskEvent: TaskEventStatic;
     SDK_VERSION: string;
   }
 
   /**
-   * An interface representing all the metadata properties that can be set.
+   * Object metadata that can be set at any time.
    *
    * This is used in updateMetadata, put, putString & putFile.
+   *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
    */
   export interface SettableMetadata {
     /**
@@ -270,28 +299,28 @@ export namespace FirebaseStorageTypes {
      *
      * [Learn more about this header on Mozilla.](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control)
      */
-    cacheControl?: string | null;
+    cacheControl?: string | undefined;
 
     /**
      * The 'Content-Disposition' HTTP header that will be set on the storage object when it's requested.
      *
      * [Learn more about this header on Mozilla.](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)
      */
-    contentDisposition?: string | null;
+    contentDisposition?: string | undefined;
 
     /**
      * The 'Content-Encoding' HTTP header that will be used on the storage object when it's requested.
      *
      * [Learn more about this header on Mozilla.](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding)
      */
-    contentEncoding?: string | null;
+    contentEncoding?: string | undefined;
 
     /**
      * The 'Content-Language' HTTP header that will be set on the storage object when it's requested.
      *
      * [Learn more about this header on Mozilla.](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Language)
      */
-    contentLanguage?: string | null;
+    contentLanguage?: string | undefined;
 
     /**
      * The 'Content-Type' HTTP header that will be set on the object when it's requested.
@@ -314,17 +343,12 @@ export namespace FirebaseStorageTypes {
      *
      * [Learn more about this header on Mozilla.](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type)
      */
-    contentType?: string | null;
-
-    /**
-     * You may specify the md5hash of the file in metadata on upload only. It may not be updated via updateMetadata
-     */
-    md5hash?: string | null;
+    contentType?: string | undefined;
 
     /**
      * Additional user-defined custom metadata for this storage object.
      *
-     * All values must be strings. Set to null to delete all. Any keys ommitted during update will be removed.
+     * All values must be strings.
      *
      * #### Example
      *
@@ -337,20 +361,31 @@ export namespace FirebaseStorageTypes {
      *   },
      * }
      */
-    customMetadata?: {
-      [key: string]: string;
-    } | null;
+    customMetadata?:
+      | {
+          [key: string]: string;
+        }
+      | undefined;
   }
 
   /**
-   * The full readable metadata returned by `TaskSnapshot.metadata` or `StorageReference.getMetadata()`.
+   * Object metadata that can be set at upload.
+   *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
    */
-  export interface FullMetadata extends SettableMetadata {
+  export interface UploadMetadata extends SettableMetadata {
     /**
-     * A Base64-encoded MD5 hash of the storage object being uploaded.
+     * A Base64-encoded MD5 hash of the object being uploaded.
      */
-    md5Hash: string | null;
+    md5Hash?: string | undefined;
+  }
 
+  /**
+   * The full readable metadata returned by `TaskSnapshot.metadata` or `StorageReference.getMetadata()`.
+   *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
+   */
+  export interface FullMetadata extends UploadMetadata {
     /**
      * The bucket this storage object is contained in.
      *
@@ -424,6 +459,16 @@ export namespace FirebaseStorageTypes {
      * ```
      */
     updated: string;
+
+    /**
+     * Tokens to allow access to the download URL.
+     */
+    downloadTokens: string[] | undefined;
+
+    /**
+     * `StorageReference` associated with this upload.
+     */
+    ref?: Reference | undefined;
   }
 
   /**
@@ -431,6 +476,8 @@ export namespace FirebaseStorageTypes {
    *
    * A reference can be used to upload and download storage objects, get/set storage object metadata, retrieve storage object download urls and delete storage objects.
    *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
+   *
    * #### Example 1
    *
    * Get a reference to a specific storage path.
@@ -594,9 +641,9 @@ export namespace FirebaseStorageTypes {
      * ```
      *
      * @param localFilePath The local file path to upload to the bucket at the reference location.
-     * @param metadata Any additional `SettableMetadata` for this task.
+     * @param metadata Any additional `UploadMetadata` for this task.
      */
-    putFile(localFilePath: string, metadata?: SettableMetadata): Task;
+    putFile(localFilePath: string, metadata?: UploadMetadata): Task;
 
     /**
      * Downloads a file to the specified local file path on the device.
@@ -629,7 +676,7 @@ export namespace FirebaseStorageTypes {
      * @param data The data to upload to the storage bucket at the reference location.
      * @param metadata
      */
-    put(data: Blob | Uint8Array | ArrayBuffer, metadata?: SettableMetadata): Task;
+    put(data: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): Task;
 
     /**
      * Puts a string on the storage bucket. Depending on the string type, set a {@link StringFormat} type.
@@ -645,12 +692,12 @@ export namespace FirebaseStorageTypes {
      *
      * @param data The string data, must match the format provided.
      * @param format The format type of the string, e.g. a Base64 format string.
-     * @param metadata Any additional `SettableMetadata` for this task.
+     * @param metadata Any additional `UploadMetadata` for this task.
      */
     putString(
       data: string,
       format?: 'raw' | 'base64' | 'base64url' | 'data_url',
-      metadata?: SettableMetadata,
+      metadata?: UploadMetadata,
     ): Task;
 
     /**
@@ -677,6 +724,8 @@ export namespace FirebaseStorageTypes {
    *
    * #### Example
    *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
+   *
    * ```js
    * const ref = firebase.storage().ref(...);
    * const task = ref.put(...)
@@ -700,19 +749,19 @@ export namespace FirebaseStorageTypes {
      *
      * @param taskSnapshot A `TaskSnapshot` for the event.
      */
-    next: (taskSnapshot: TaskSnapshot) => void;
+    next?: (taskSnapshot: TaskSnapshot) => void;
 
     /**
      * Called when the task errors.
      *
      * @param error A JavaScript error.
      */
-    error: (error: NativeFirebaseError) => void;
+    error?: (error: NativeFirebaseError) => void;
 
     /**
      * Called when the task has completed successfully.
      */
-    complete: () => void;
+    complete?: () => void;
   }
 
   /**
@@ -720,6 +769,8 @@ export namespace FirebaseStorageTypes {
    *
    * #### Example 1
    *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
+   *
    * Get a Upload Storage task to upload a string:
    *
    * ```js
@@ -859,6 +910,8 @@ export namespace FirebaseStorageTypes {
    *
    * #### Example 1
    *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
+   *
    * ```js
    * firebase
    *   .storage()
@@ -906,7 +959,7 @@ export namespace FirebaseStorageTypes {
     /**
      * The current state of the task snapshot.
      */
-    state: 'cancelled' | 'error' | 'paused' | 'running' | 'success';
+    state: TaskState;
 
     /**
      * The parent {@link Task} of this snapshot.
@@ -927,6 +980,8 @@ export namespace FirebaseStorageTypes {
 
   /**
    * Result returned from a non-resumable upload.
+   *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
    */
   export interface TaskResult {
     /**
@@ -942,6 +997,8 @@ export namespace FirebaseStorageTypes {
 
   /**
    * The options `list()` accepts.
+   *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
    */
   export interface ListOptions {
     /**
@@ -952,11 +1009,13 @@ export namespace FirebaseStorageTypes {
     /**
      * The `nextPageToken` from a previous call to `list()`. If provided, listing is resumed from the previous position.
      */
-    pageToken?: string;
+    pageToken?: string | null;
   }
 
   /**
    * Result returned by `list()`.
+   *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
    */
   export interface ListResult {
     /**
@@ -979,6 +1038,8 @@ export namespace FirebaseStorageTypes {
 
   /**
    * Storage Emulator options. Web only.
+   *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
    */
   export interface EmulatorMockTokenOptions {
     /**
@@ -992,6 +1053,8 @@ export namespace FirebaseStorageTypes {
    *
    * #### Example 1
    *
+   * @deprecated Use the exported types directly instead. FirebaseStorageTypes namespace is kept for backwards compatibility.
+   *
    * Get the storage instance for the **default app**:
    *
    * ```js
@@ -1020,7 +1083,7 @@ export namespace FirebaseStorageTypes {
    * ```
    *
    */
-  export class Module extends FirebaseModule {
+  export interface Module extends FirebaseModule {
     /**
      * The current `FirebaseApp` instance for this Firebase service.
      */
@@ -1141,8 +1204,8 @@ export namespace FirebaseStorageTypes {
      * If you want to use the emulator on a real android device, you will need to specify the actual host
      * computer IP address.
      *
-     * @param host: emulator host (eg, 'localhost')
-     * @param port: emulator port (eg, 9199)
+     * @param host emulator host (eg, 'localhost')
+     * @param port emulator port (eg, 9199)
      */
     useEmulator(host: string, port: number): void;
   }
@@ -1158,7 +1221,7 @@ type StorageNamespace = ReactNativeFirebase.FirebaseModuleWithStaticsAndApp<
 
 declare const defaultExport: StorageNamespace;
 
-export const firebase: ReactNativeFirebase.Module & {
+export declare const firebase: ReactNativeFirebase.Module & {
   storage: typeof defaultExport;
   app(name?: string): ReactNativeFirebase.FirebaseApp & { storage(): FirebaseStorageTypes.Module };
 };
@@ -1168,6 +1231,7 @@ export default defaultExport;
 /**
  * Attach namespace to `firebase.` and `FirebaseApp.`.
  */
+
 declare module '@react-native-firebase/app' {
   namespace ReactNativeFirebase {
     import FirebaseModuleWithStaticsAndApp = ReactNativeFirebase.FirebaseModuleWithStaticsAndApp;
@@ -1182,5 +1246,3 @@ declare module '@react-native-firebase/app' {
     }
   }
 }
-
-export * from './modular';