@cloudbase/js-sdk 3.1.7 → 3.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.d.ts CHANGED
@@ -78,11 +78,19 @@ declare namespace cloudbase {
78
78
  }
79
79
 
80
80
  interface ICloudbaseConfig {
81
+ /** 环境 ID,在腾讯云开发控制台 → 环境 → 环境总览中获取 */
81
82
  env: string
83
+ /**
84
+ * 地域信息
85
+ * @example 'ap-shanghai'
86
+ */
82
87
  region?: string
88
+ /** 网络请求超时上限,单位 ms,默认 15000 */
83
89
  timeout?: number
90
+ /** 本地登录态保留期限 */
84
91
  persistence?: Persistence
85
92
  oauthClient?: any
93
+ /** 是否开启调试模式 */
86
94
  debug?: boolean
87
95
  _fromApp?: ICloudbase
88
96
  clientId?: string
@@ -95,7 +103,31 @@ declare namespace cloudbase {
95
103
  }
96
104
  accessKey?: string
97
105
  endPointMode?: EndPointKey
98
- lang?: LANGS
106
+ lang?: LANGS
107
+ /**
108
+ * 认证相关配置
109
+ * @example
110
+ * ```typescript
111
+ * cloudbase.init({
112
+ * env: 'your-env-id',
113
+ * auth: {
114
+ * detectSessionInUrl: true // 自动检测 URL 中的 OAuth 回调参数
115
+ * }
116
+ * })
117
+ * ```
118
+ */
119
+ auth?: {
120
+ /** 是否自动检测 URL 中的 OAuth 回调参数,默认 false */
121
+ detectSessionInUrl?: boolean
122
+ /** 密钥 ID(Node.js 端使用) */
123
+ secretId?: string
124
+ /** 密钥(Node.js 端使用) */
125
+ secretKey?: string
126
+ /** 临时会话 Token(Node.js 端使用) */
127
+ sessionToken?: string
128
+ /** 密钥类型 */
129
+ secretType?: 'SESSION_SECRET' | 'SECRET'
130
+ }
99
131
  }
100
132
 
101
133
  interface ICloudbaseExtension {
@@ -148,20 +180,49 @@ declare namespace cloudbase {
148
180
  *
149
181
  * @example
150
182
  * ```javascript
183
+ * // 基本用法
151
184
  * const app = cloudbase.init({
152
185
  * env: 'your-envid',
153
186
  * timeout: 15000
154
187
  * });
188
+ *
189
+ * // 推荐:从环境变量读取环境 ID
190
+ * const app = cloudbase.init({
191
+ * env: process.env.CLOUDBASE_ENV || import.meta.env.VITE_CLOUDBASE_ENV || 'your-envid'
192
+ * });
193
+ *
194
+ * // 使用认证配置
195
+ * const app = cloudbase.init({
196
+ * env: 'your-envid',
197
+ * auth: {
198
+ * detectSessionInUrl: true // 自动检测 URL 中的 OAuth 回调参数
199
+ * }
200
+ * });
155
201
  * ```
156
202
  *
157
203
  * @param config 初始化配置
158
- * @param config.env 环境ID
204
+ * @param config.env 环境ID,在腾讯云开发控制台 → 环境 → 环境总览中获取
159
205
  * @param config.timeout 【可选】网络请求超时上限,单位`ms`,默认值`15000`
206
+ * @param config.auth 【可选】认证相关配置
160
207
  *
161
208
  * @return {!cloudbase.app.App} 初始化成功的Cloudbase实例
162
209
  */
163
210
  function init(config: ICloudbaseConfig): cloudbase.app.App
164
211
 
212
+ /**
213
+ * 检查 Cloudbase 实例是否已完成初始化
214
+ *
215
+ * @example
216
+ * ```javascript
217
+ * if (!cloudbase.isInitialized()) {
218
+ * cloudbase.init({ env: 'your-envid' });
219
+ * }
220
+ * ```
221
+ *
222
+ * @returns 是否已初始化
223
+ */
224
+ function isInitialized(): boolean
225
+
165
226
  function updateConfig(config: ICloudbaseUpgradedConfig): void
166
227
 
167
228
  function updateLang(lang: LANGS): void
@@ -512,8 +573,7 @@ declare namespace cloudbase.app {
512
573
 
513
574
  getFileInfo(
514
575
  params: cloudbase.storage.ICloudbaseGetTempFileURLParams,
515
- callback?: Function,
516
- ): Promise<cloudbase.storage.ICloudbaseGetTempFileURLResult>
576
+ ): Promise<cloudbase.storage.ICloudbaseGetFileInfoResult>
517
577
  /**
518
578
  * 云存储-获取上传元信息
519
579
  *
@@ -522,6 +582,17 @@ declare namespace cloudbase.app {
522
582
  * @param callback
523
583
  */
524
584
  getUploadMetadata(params: cloudbase.storage.ICloudbaseGetUploadMetadataParams, callback?: Function): Promise<any>
585
+
586
+ /**
587
+ * Supabase 风格的文件存储 API
588
+ *
589
+ * @example
590
+ * ```typescript
591
+ * const bucket = app.storage.from('my-bucket')
592
+ * const { data, error } = await bucket.upload('path/to/file.jpg', file)
593
+ * ```
594
+ */
595
+ storage: cloudbase.storage.SupabaseFileAPILikeStorage
525
596
  /**
526
597
  * 获取数据库实例
527
598
  *
@@ -1308,6 +1379,296 @@ declare namespace cloudbase.auth {
1308
1379
  * @param params
1309
1380
  */
1310
1381
  signInWithPhoneAuth(params: { phoneCode: string }): Promise<SignInRes>
1382
+
1383
+ // ========== v1 兼容 API ==========
1384
+
1385
+ /**
1386
+ * v1 API: 获取用于微信登录的 WeixinAuthProvider
1387
+ *
1388
+ * @deprecated 建议使用 auth.signInWithOAuth({ provider: appid }) 替代。
1389
+ *
1390
+ * @example
1391
+ * ```javascript
1392
+ * const provider = auth.weixinAuthProvider({ appid: 'wx-appid', scope: 'snsapi_login' });
1393
+ * provider.signInWithRedirect();
1394
+ * ```
1395
+ *
1396
+ * @param options
1397
+ * @param options.appid 微信 AppID
1398
+ * @param options.scope 微信授权范围
1399
+ */
1400
+ weixinAuthProvider(options: { appid: string; scope: string }): cloudbase.auth.WeixinAuthProvider
1401
+
1402
+ /**
1403
+ * v1 API: 获取用于自定义登录的 CustomAuthProvider
1404
+ *
1405
+ * @deprecated 建议使用 auth.signInWithCustomTicket(() => Promise.resolve(ticket)) 替代。
1406
+ *
1407
+ * @example
1408
+ * ```javascript
1409
+ * const provider = auth.customAuthProvider();
1410
+ * await provider.signIn(ticket);
1411
+ * ```
1412
+ */
1413
+ customAuthProvider(): cloudbase.auth.CustomAuthProvider
1414
+
1415
+ /**
1416
+ * v1 API: 获取用于匿名登录的 AnonymousAuthProvider
1417
+ *
1418
+ * @deprecated 建议使用 auth.signInAnonymously({}) 替代。
1419
+ *
1420
+ * @example
1421
+ * ```javascript
1422
+ * const provider = auth.anonymousAuthProvider();
1423
+ * await provider.signIn();
1424
+ * ```
1425
+ */
1426
+ anonymousAuthProvider(): cloudbase.auth.AnonymousAuthProvider
1427
+
1428
+ /**
1429
+ * v1 API: 使用邮箱和密码注册云开发账户
1430
+ *
1431
+ * @deprecated 建议使用 auth.signUp({ email, password }) 替代。
1432
+ *
1433
+ * @example
1434
+ * ```javascript
1435
+ * await auth.signUpWithEmailAndPassword('user@example.com', 'password123');
1436
+ * ```
1437
+ *
1438
+ * @param email 邮箱
1439
+ * @param password 密码
1440
+ */
1441
+ signUpWithEmailAndPassword(email: string, password: string): Promise<SignUpRes>
1442
+
1443
+ /**
1444
+ * v1 API: 使用邮箱和密码登录云开发(支持两种调用方式)
1445
+ *
1446
+ * @deprecated 建议使用 auth.signInWithPassword({ email, password }) 替代。
1447
+ *
1448
+ * @example
1449
+ * ```javascript
1450
+ * // 方式一(v1 风格):
1451
+ * await auth.signInWithEmailAndPassword('user@example.com', 'password123');
1452
+ *
1453
+ * // 方式二(v3 风格):
1454
+ * const { data, error } = await auth.signInWithEmailAndPassword({
1455
+ * email: 'user@example.com',
1456
+ * password: 'password123'
1457
+ * });
1458
+ * ```
1459
+ *
1460
+ * @param emailOrParams - 邮箱字符串(v1)或包含 email 和 password 的对象(v3)
1461
+ * @param password - 密码(仅 v1 风格时使用)
1462
+ */
1463
+ signInWithEmailAndPassword(emailOrParams: string | { email: string; password: string; is_encrypt?: boolean }, password?: string): Promise<SignInRes | ILoginState>
1464
+
1465
+ /**
1466
+ * v1 API: 发送重置密码的邮件
1467
+ *
1468
+ * @deprecated 建议使用 auth.resetPasswordForEmail(email) 替代。
1469
+ *
1470
+ * @example
1471
+ * ```javascript
1472
+ * await auth.sendPasswordResetEmail('user@example.com');
1473
+ * ```
1474
+ *
1475
+ * @param email 邮箱
1476
+ */
1477
+ sendPasswordResetEmail(email: string): Promise<void>
1478
+
1479
+ /**
1480
+ * v1 API: 使用用户名和密码登录云开发
1481
+ *
1482
+ * @deprecated 建议使用 auth.signInWithPassword({ username, password }) 替代。
1483
+ *
1484
+ * @example
1485
+ * ```javascript
1486
+ * const loginState = await auth.signInWithUsernameAndPassword('username', 'password123');
1487
+ * ```
1488
+ *
1489
+ * @param username 用户名
1490
+ * @param password 密码
1491
+ */
1492
+ signInWithUsernameAndPassword(username: string, password: string): Promise<ILoginState>
1493
+
1494
+ /**
1495
+ * v1 API: 发送手机验证码
1496
+ *
1497
+ * @deprecated 建议使用 auth.signInWithOtp({ phone }) 或 auth.getVerification({ phone_number }) 替代。
1498
+ *
1499
+ * @example
1500
+ * ```javascript
1501
+ * const success = await auth.sendPhoneCode('+8613800138000');
1502
+ * ```
1503
+ *
1504
+ * @param phoneNumber 手机号
1505
+ * @returns 是否发送成功
1506
+ */
1507
+ sendPhoneCode(phoneNumber: string): Promise<boolean>
1508
+
1509
+ /**
1510
+ * v1 API: 手机号注册(支持短信验证码+密码方式)
1511
+ *
1512
+ * @deprecated 建议使用 auth.signUp({ phone_number, verification_code, password? }) 替代。
1513
+ *
1514
+ * @example
1515
+ * ```javascript
1516
+ * const loginState = await auth.signUpWithPhoneCode('+8613800138000', '123456', 'password');
1517
+ * ```
1518
+ *
1519
+ * @param phoneNumber 手机号
1520
+ * @param phoneCode 验证码
1521
+ * @param password 可选密码
1522
+ */
1523
+ signUpWithPhoneCode(phoneNumber: string, phoneCode: string, password?: string): Promise<ILoginState>
1524
+
1525
+ /**
1526
+ * v1 API: 手机号登录(支持短信验证码 or 密码方式)
1527
+ *
1528
+ * @deprecated 密码方式建议使用 auth.signInWithPassword({ phone, password }) 替代;
1529
+ * 验证码方式建议使用 auth.signInWithOtp({ phone }) 替代。
1530
+ *
1531
+ * @example
1532
+ * ```javascript
1533
+ * // 验证码登录
1534
+ * const loginState = await auth.signInWithPhoneCodeOrPassword({
1535
+ * phoneNumber: '+8613800138000',
1536
+ * phoneCode: '123456'
1537
+ * });
1538
+ *
1539
+ * // 密码登录
1540
+ * const loginState = await auth.signInWithPhoneCodeOrPassword({
1541
+ * phoneNumber: '+8613800138000',
1542
+ * password: 'password123'
1543
+ * });
1544
+ * ```
1545
+ *
1546
+ * @param params
1547
+ */
1548
+ signInWithPhoneCodeOrPassword(params: {
1549
+ phoneNumber: string
1550
+ phoneCode?: string
1551
+ password?: string
1552
+ }): Promise<ILoginState>
1553
+
1554
+ /**
1555
+ * v1 API: 手机号强制重置密码
1556
+ *
1557
+ * @deprecated 建议使用 auth.resetPasswordForEmail(phoneNumber) 替代。
1558
+ *
1559
+ * @example
1560
+ * ```javascript
1561
+ * const loginState = await auth.forceResetPwdByPhoneCode({
1562
+ * phoneNumber: '+8613800138000',
1563
+ * phoneCode: '123456',
1564
+ * password: 'newPassword'
1565
+ * });
1566
+ * ```
1567
+ *
1568
+ * @param params
1569
+ */
1570
+ forceResetPwdByPhoneCode(params: {
1571
+ phoneNumber: string
1572
+ phoneCode: string
1573
+ password: string
1574
+ }): Promise<ILoginState>
1575
+
1576
+ /**
1577
+ * v1 API: 接收一个回调函数,在刷新短期访问令牌前调用,根据返回值决定是否刷新
1578
+ *
1579
+ * @deprecated 建议使用 auth.onAuthStateChange(callback) 监听 TOKEN_REFRESHED 事件替代。
1580
+ *
1581
+ * @param callback 回调函数,返回 true 则刷新,返回 false 则不刷新
1582
+ */
1583
+ shouldRefreshAccessToken(callback: () => boolean): void
1584
+
1585
+ /**
1586
+ * v1 API: 接收一个回调函数,在登录状态过期时调用
1587
+ *
1588
+ * @deprecated 建议使用 auth.onAuthStateChange(callback) 替代,监听 SIGNED_OUT 事件。
1589
+ *
1590
+ * @param callback 登录态过期回调
1591
+ */
1592
+ onLoginStateExpired(callback: Function): void
1593
+
1594
+ /**
1595
+ * v1 API: 接收一个回调函数,在短期访问令牌刷新后调用
1596
+ *
1597
+ * @deprecated 建议使用 auth.onAuthStateChange(callback) 替代,监听 TOKEN_REFRESHED 事件。
1598
+ *
1599
+ * @param callback 令牌刷新回调
1600
+ */
1601
+ onAccessTokenRefreshed(callback: Function): void
1602
+
1603
+ /**
1604
+ * v1 API: 接收一个回调函数,在匿名登录状态被转换后调用
1605
+ *
1606
+ * @deprecated 建议使用 auth.onAuthStateChange(callback) 替代,监听 SIGNED_IN 事件。
1607
+ *
1608
+ * @param callback 匿名转正回调
1609
+ */
1610
+ onAnonymousConverted(callback: Function): void
1611
+
1612
+ /**
1613
+ * v1 API: 接收一个回调函数,在登录类型发生变化后调用
1614
+ *
1615
+ * @deprecated 建议使用 auth.onAuthStateChange(callback) 替代,监听 SIGNED_IN / SIGNED_OUT 事件。
1616
+ *
1617
+ * @param callback 登录类型变化回调
1618
+ */
1619
+ onLoginTypeChanged(callback: Function): void
1620
+ }
1621
+
1622
+ // ========== v1 兼容 Provider 类 ==========
1623
+
1624
+ /**
1625
+ * v1 微信登录 Provider
1626
+ *
1627
+ * @deprecated 建议使用 auth.signInWithOAuth({ provider }) 替代。
1628
+ */
1629
+ interface WeixinAuthProvider {
1630
+ /**
1631
+ * 跳转微信授权页面进行登录
1632
+ * @deprecated 建议使用 auth.signInWithOAuth({ provider: 'providerId' }) 替代。
1633
+ */
1634
+ signInWithRedirect(): void
1635
+ /**
1636
+ * 获取微信授权重定向结果
1637
+ * @deprecated 建议使用 auth.verifyOAuth({ code, state, provider }) 替代。
1638
+ */
1639
+ getRedirectResult(options?: { createUser?: boolean; syncUserInfo?: boolean }): Promise<any>
1640
+ /**
1641
+ * 获取微信绑定重定向结果
1642
+ * @deprecated 建议使用 auth.linkIdentity({ provider: 'providerId' }) 替代。
1643
+ */
1644
+ getLinkRedirectResult(options?: { withUnionId?: boolean }): Promise<void>
1645
+ }
1646
+
1647
+ /**
1648
+ * v1 自定义登录 Provider
1649
+ *
1650
+ * @deprecated 建议使用 auth.signInWithCustomTicket(() => Promise.resolve(ticket)) 替代。
1651
+ */
1652
+ interface CustomAuthProvider {
1653
+ /**
1654
+ * 使用自定义登录凭据 ticket 登录云开发
1655
+ * @param ticket 自定义登录 ticket
1656
+ * @deprecated 建议使用 auth.signInWithCustomTicket(() => Promise.resolve(ticket)) 替代。
1657
+ */
1658
+ signIn(ticket: string): Promise<void>
1659
+ }
1660
+
1661
+ /**
1662
+ * v1 匿名登录 Provider
1663
+ *
1664
+ * @deprecated 建议使用 auth.signInAnonymously({}) 替代。
1665
+ */
1666
+ interface AnonymousAuthProvider {
1667
+ /**
1668
+ * 匿名登录云开发
1669
+ * @deprecated 建议使用 auth.signInAnonymously({}) 替代。
1670
+ */
1671
+ signIn(): Promise<void>
1311
1672
  }
1312
1673
  }
1313
1674
  /**
@@ -1428,6 +1789,365 @@ declare namespace cloudbase.storage {
1428
1789
  }>
1429
1790
  requestId?: string
1430
1791
  }
1792
+
1793
+ interface ICloudbaseGetFileInfoResultItem {
1794
+ code?: string
1795
+ message?: string
1796
+ fileID: string
1797
+ tempFileURL: string
1798
+ fileName?: string
1799
+ cloudId?: string
1800
+ contentType?: string
1801
+ mime?: string
1802
+ size?: number
1803
+ cacheControl?: string
1804
+ lastModified?: string
1805
+ etag?: string
1806
+ }
1807
+
1808
+ interface ICloudbaseGetFileInfoResult {
1809
+ fileList: ICloudbaseGetFileInfoResultItem[]
1810
+ requestId: string
1811
+ }
1812
+
1813
+ // ---- Supabase-like Storage Types ----
1814
+
1815
+ type FileBody =
1816
+ | ArrayBuffer
1817
+ | ArrayBufferView
1818
+ | Blob
1819
+ | Buffer
1820
+ | File
1821
+ | FormData
1822
+ | NodeJS.ReadableStream
1823
+ | ReadableStream<Uint8Array>
1824
+ | URLSearchParams
1825
+ | string
1826
+
1827
+ interface FileOptions {
1828
+ cacheControl?: string
1829
+ contentType?: string
1830
+ upsert?: boolean
1831
+ duplex?: string
1832
+ metadata?: Record<string, any>
1833
+ headers?: Record<string, string>
1834
+ }
1835
+
1836
+ interface TransformOptions {
1837
+ width?: number
1838
+ height?: number
1839
+ resize?: 'cover' | 'contain' | 'fill'
1840
+ quality?: number
1841
+ format?: 'origin'
1842
+ }
1843
+
1844
+ interface FileObject {
1845
+ name: string
1846
+ bucket_id: string
1847
+ owner: string
1848
+ id: string
1849
+ updated_at: string
1850
+ created_at: string
1851
+ /** @deprecated */
1852
+ last_accessed_at: string
1853
+ metadata: Record<string, any>
1854
+ buckets: {
1855
+ id: string
1856
+ name: string
1857
+ owner: string
1858
+ public: boolean
1859
+ created_at: string
1860
+ updated_at: string
1861
+ }
1862
+ }
1863
+
1864
+ interface FileObjectV2 {
1865
+ id: string
1866
+ version: string
1867
+ name: string
1868
+ bucketId: string
1869
+ updatedAt: string
1870
+ createdAt: string
1871
+ /** @deprecated */
1872
+ lastAccessedAt: string
1873
+ size?: number
1874
+ cacheControl?: string
1875
+ contentType?: string
1876
+ etag?: string
1877
+ lastModified?: string
1878
+ metadata?: Record<string, any>
1879
+ }
1880
+
1881
+ class StorageError extends Error {
1882
+ name: 'StorageError'
1883
+ constructor(message: string)
1884
+ }
1885
+
1886
+ /**
1887
+ * Supabase 风格的文件存储 API
1888
+ *
1889
+ * 通过 `app.storage` 获取实例,提供类似 Supabase Storage 的操作接口。
1890
+ *
1891
+ * @example
1892
+ * ```typescript
1893
+ * const app = cloudbase.init({ env: 'your-envid' })
1894
+ * const bucket = app.storage.from('my-bucket')
1895
+ *
1896
+ * // 上传文件
1897
+ * const { data, error } = await bucket.upload('path/to/file.jpg', file)
1898
+ *
1899
+ * // 获取签名 URL
1900
+ * const { data } = await bucket.createSignedUrl('path/to/file.jpg', 3600)
1901
+ *
1902
+ * // 下载文件
1903
+ * const { data } = await bucket.download('path/to/file.jpg')
1904
+ * ```
1905
+ */
1906
+ interface SupabaseFileAPILikeStorage {
1907
+ /**
1908
+ * 启用错误抛出模式,而非返回 `{ data: null, error }` 格式
1909
+ */
1910
+ throwOnError(): this
1911
+
1912
+ /**
1913
+ * 选择存储桶
1914
+ *
1915
+ * @param bucket 存储桶名称
1916
+ * @returns 当前实例(链式调用)
1917
+ *
1918
+ * @example
1919
+ * ```typescript
1920
+ * const bucket = app.storage.from('my-bucket')
1921
+ * ```
1922
+ */
1923
+ from(bucket?: string): this
1924
+
1925
+ /**
1926
+ * 上传文件
1927
+ *
1928
+ * @param path 文件路径
1929
+ * @param fileBody 文件内容
1930
+ * @param fileOptions 上传选项
1931
+ */
1932
+ upload(
1933
+ path: string,
1934
+ fileBody: FileBody,
1935
+ fileOptions?: FileOptions,
1936
+ ): Promise<
1937
+ | { data: { id: string; path: string; fullPath: string }; error: null }
1938
+ | { data: null; error: StorageError }
1939
+ >
1940
+
1941
+ /**
1942
+ * 上传文件到已签名的 URL
1943
+ *
1944
+ * @param path 文件路径
1945
+ * @param token 签名 Token
1946
+ * @param fileBody 文件内容
1947
+ * @param fileOptions 上传选项
1948
+ */
1949
+ uploadToSignedUrl(
1950
+ path: string,
1951
+ token: string,
1952
+ fileBody: FileBody,
1953
+ fileOptions?: FileOptions,
1954
+ ): Promise<
1955
+ | { data: { id: string; path: string; fullPath: string }; error: null }
1956
+ | { data: null; error: StorageError }
1957
+ >
1958
+
1959
+ /**
1960
+ * 创建用于上传的签名 URL
1961
+ *
1962
+ * @param path 文件路径
1963
+ */
1964
+ createSignedUploadUrl(path: string): Promise<
1965
+ | {
1966
+ data: {
1967
+ signedUrl: string
1968
+ token: string
1969
+ path: string
1970
+ authorization?: string
1971
+ id?: string
1972
+ cosFileId?: string
1973
+ downloadUrl?: string
1974
+ }
1975
+ error: null
1976
+ }
1977
+ | { data: null; error: StorageError }
1978
+ >
1979
+
1980
+ /**
1981
+ * 更新(覆盖)文件
1982
+ *
1983
+ * @param path 文件路径
1984
+ * @param fileBody 文件内容
1985
+ * @param fileOptions 上传选项
1986
+ */
1987
+ update(
1988
+ path: string,
1989
+ fileBody: FileBody,
1990
+ fileOptions?: FileOptions,
1991
+ ): Promise<
1992
+ | { data: { id: string; path: string; fullPath: string }; error: null }
1993
+ | { data: null; error: StorageError }
1994
+ >
1995
+
1996
+ /**
1997
+ * 移动文件(复制后删除源文件)
1998
+ *
1999
+ * @param fromPath 源文件路径
2000
+ * @param toPath 目标文件路径
2001
+ */
2002
+ move(
2003
+ fromPath: string,
2004
+ toPath: string,
2005
+ ): Promise<
2006
+ | { data: { message: string }; error: null }
2007
+ | { data: null; error: StorageError }
2008
+ >
2009
+
2010
+ /**
2011
+ * 复制文件
2012
+ *
2013
+ * @param fromPath 源文件路径
2014
+ * @param toPath 目标文件路径
2015
+ */
2016
+ copy(
2017
+ fromPath: string,
2018
+ toPath: string,
2019
+ ): Promise<
2020
+ | { data: { path: string }; error: null }
2021
+ | { data: null; error: StorageError }
2022
+ >
2023
+
2024
+ /**
2025
+ * 创建签名下载 URL
2026
+ *
2027
+ * @param path 文件路径
2028
+ * @param expiresIn 有效期(秒)
2029
+ * @param options 可选配置
2030
+ */
2031
+ createSignedUrl(
2032
+ path: string,
2033
+ expiresIn: number,
2034
+ options?: {
2035
+ download?: string | boolean
2036
+ transform?: TransformOptions
2037
+ },
2038
+ ): Promise<
2039
+ | { data: { signedUrl: string }; error: null }
2040
+ | { data: null; error: StorageError }
2041
+ >
2042
+
2043
+ /**
2044
+ * 批量创建签名下载 URL
2045
+ *
2046
+ * @param paths 文件路径数组
2047
+ * @param expiresIn 有效期(秒)
2048
+ */
2049
+ createSignedUrls(
2050
+ paths: string[],
2051
+ expiresIn: number,
2052
+ ): Promise<
2053
+ | { data: Array<{ path: string; signedUrl: string; error: string | null }>; error: null }
2054
+ | { data: null; error: StorageError }
2055
+ >
2056
+
2057
+ /**
2058
+ * 下载文件,返回 Blob
2059
+ *
2060
+ * @param path 文件路径
2061
+ * @param options 图片转换选项
2062
+ */
2063
+ download(
2064
+ path: string,
2065
+ options?: TransformOptions,
2066
+ ): Promise<{ data: Blob; error: StorageError | null }>
2067
+
2068
+ /**
2069
+ * 获取文件详细信息
2070
+ *
2071
+ * @param pathOrFileId 相对路径或 CloudBase fileID
2072
+ */
2073
+ info(pathOrFileId: string): Promise<
2074
+ | { data: FileObjectV2; error: null }
2075
+ | { data: null; error: StorageError }
2076
+ >
2077
+
2078
+ /**
2079
+ * 检查文件是否存在
2080
+ *
2081
+ * @param pathOrFileId 相对路径或 CloudBase fileID
2082
+ */
2083
+ exists(pathOrFileId: string): Promise<
2084
+ | { data: boolean; error: null }
2085
+ | { data: null; error: StorageError }
2086
+ >
2087
+
2088
+ /**
2089
+ * 获取文件的公开 URL
2090
+ *
2091
+ * @param path 文件路径
2092
+ * @param options 可选配置
2093
+ */
2094
+ getPublicUrl(
2095
+ path: string,
2096
+ options?: {
2097
+ download?: string | boolean
2098
+ transform?: TransformOptions
2099
+ },
2100
+ ): Promise<
2101
+ | { data: { publicUrl: string } }
2102
+ | { data: null; error: StorageError }
2103
+ >
2104
+
2105
+ /**
2106
+ * 批量删除文件
2107
+ *
2108
+ * @param paths 文件路径数组
2109
+ */
2110
+ remove(paths: string[]): Promise<
2111
+ | { data: FileObject[]; error: null }
2112
+ | { data: null; error: StorageError }
2113
+ >
2114
+
2115
+ // ---- 继承自 CloudbaseStorage 的方法 ----
2116
+
2117
+ uploadFile(
2118
+ params: ICloudbaseUploadFileParams,
2119
+ callback?: Function,
2120
+ ): Promise<ICloudbaseUploadFileResult>
2121
+
2122
+ deleteFile(
2123
+ params: ICloudbaseDeleteFileParams,
2124
+ callback?: Function,
2125
+ ): Promise<ICloudbaseDeleteFileResult>
2126
+
2127
+ getTempFileURL(
2128
+ params: ICloudbaseGetTempFileURLParams,
2129
+ callback?: Function,
2130
+ ): Promise<ICloudbaseGetTempFileURLResult>
2131
+
2132
+ downloadFile(
2133
+ params: ICloudbaseDownloadFileParams,
2134
+ callback?: Function,
2135
+ ): Promise<ICloudbaseDownloadFileResult>
2136
+
2137
+ getUploadMetadata(
2138
+ params: ICloudbaseGetUploadMetadataParams,
2139
+ callback?: Function,
2140
+ ): Promise<ICloudbaseFileMetaDataRes>
2141
+
2142
+ copyFile(
2143
+ params: ICloudbaseCopyFileParams,
2144
+ callback?: Function,
2145
+ ): Promise<ICloudbaseCopyFileResult>
2146
+
2147
+ getFileInfo(
2148
+ params: ICloudbaseGetTempFileURLParams,
2149
+ ): Promise<ICloudbaseGetFileInfoResult>
2150
+ }
1431
2151
  }
1432
2152
 
1433
2153
  declare namespace cloudbase.database {
@@ -2640,10 +3360,19 @@ declare namespace cloudbase.database {
2640
3360
  /**
2641
3361
  * 创建集合
2642
3362
  *
3363
+ * **⚠️ 权限说明**:此方法通常需要管理员权限,客户端 SDK(Web/小程序)在默认安全规则下
3364
+ * 可能无权限调用此方法。如果调用失败,请通过以下方式创建集合:
3365
+ * 1. 登录[腾讯云开发控制台](https://console.cloud.tencent.com/tcb/database)手动创建
3366
+ * 2. 在云函数中使用管理端 SDK 创建
3367
+ * 3. 使用 CLI 工具创建:`tcb service:collection-create <collName>`
3368
+ *
2643
3369
  * {@link https://docs.cloudbase.net/api-reference/webv3-next/database#createcollection}
2644
3370
  *
2645
3371
  * @example
3372
+ * ```javascript
3373
+ * // 管理端 SDK 或具有管理员权限时可用
2646
3374
  * const result = await db.createCollection('new-collection')
3375
+ * ```
2647
3376
  *
2648
3377
  * @param collName 集合名称
2649
3378
  *
@@ -2716,5 +3445,5 @@ declare namespace cloudbase.database {
2716
3445
  }
2717
3446
  }
2718
3447
 
2719
- export default cloudbase
3448
+ export = cloudbase
2720
3449
  export as namespace cloudbase