k2-im 0.1.17 → 0.1.18

package/dist/browser.js

@@ -1 +1 @@
-export{A as createLazyBrowserApiProtocolClient}from'./chunk-K6P5ZYHG.js';import'./chunk-KTWXKQ4J.js';import'./chunk-WOT6VMZA.js';
+export{A as createLazyBrowserApiProtocolClient}from'./chunk-DFJWOEGQ.js';import'./chunk-RKZTPXBQ.js';import'./chunk-WOT6VMZA.js';

package/dist/chat-kit-pinia.d.ts

@@ -1,7 +1,7 @@
 import * as pinia from 'pinia';
 import { Pinia, Store } from 'pinia';
 
-/** 媒体业务类型：实现据此选对象存储 bucket/host；sticker 对应 app-sticker。 */
+/** 媒体业务类型：实现据此选对象存储逻辑桶；sticker 对应 app-sticker。 */
 type MediaKind = 'image' | 'video' | 'voice' | 'file' | 'sticker';
 
 /** 会话类型。P0 只用 direct / group。 */
@@ -2492,20 +2492,69 @@ interface MembershipJoinResult {
     outcome: MembershipJoinOutcome;
 }
 
-/** 单个媒体类型的对象存储位置：bucket + 公网 host（URL = host/key）。 */
-interface MediaBucketConfig {
+/** 服务端按逻辑桶签发的 S3 临时上传凭证（已归一为 SDK 合同字段）。 */
+interface MediaUploadCredentials {
+    /** STS access key id（服务端字段 `access_key_id`）。 */
+    accessKeyId: string;
+    /** STS secret access key（服务端字段 `secret_key`）。 */
+    secretAccessKey: string;
+    /** STS session token（服务端字段 `session_token`）。 */
+    sessionToken: string;
+    /** 服务端声明的过期时间（Unix 秒）；缺省时该凭证只受 SDK 本地 TTL 约束。 */
+    expiresAtSeconds?: number;
+    /** 服务端解析出的**物理桶**名，可能与申请用的逻辑桶名不同；PutObject 必须用它。 */
     bucket: string;
-    host: string;
+    /** 物理桶所在区域，决定上传端点；不再从身份池 id 前缀推断。 */
+    region: string;
+    /** 对象 key 前缀；STS 策略只允许写该前缀下的对象，SDK 生成的 key 必须以它开头。 */
+    keyPrefix?: string;
+    /** 公开访问域名（已归一为带 scheme、无尾斜杠）；写进消息体的媒体 URL 以它为准。 */
+    dnsPoint: string;
+    /** 服务端身份标识；SDK 不使用，仅原样透出供宿主排查。 */
+    identityId?: string;
+}
+/** SDK 向宿主申请凭证时给出的上下文。 */
+interface MediaUploadCredentialsRequest {
+    /** 宿主 env 配置的**逻辑桶名**；宿主原样提交给自己的 BFF。 */
+    bucket: string;
+    /** true 表示 SDK 判定旧凭证不可用（上传被拒或已过期），宿主必须真的重新请求，不得返回自己的缓存。 */
+    forceRefresh: boolean;
 }
+/**
+ * 宿主注入的取凭证函数：按逻辑桶名向宿主自己的 BFF 申请一次 STS 临时凭证。
+ *
+ * @remarks 这里刻意不带 `AbortSignal`：同一逻辑桶的并发上传会共用同一次在途请求，
+ * 单个上传被取消不应连带中止其它上传正在等待的凭证。宿主实现应当是「打一次接口」的纯函数，
+ * 缓存、TTL、单飞与失败重签由 SDK 负责。
+ */
+type MediaUploadCredentialsProvider = (request: MediaUploadCredentialsRequest) => Promise<MediaUploadCredentials>;
+
 interface MediaTransferAdapterConfig {
-    /** AWS Cognito 身份池 id（形如 `ap-northeast-1:xxxx`；region 从前缀解析）。 */
-    identityPoolId: string;
-    /** 群、社群与用户头像使用的独立 app-header bucket/host；不得复用聊天图片桶。 */
-    avatar?: MediaBucketConfig;
-    /** 各媒体类型的 bucket/host 映射（对齐 Android：image→app-image 等）。 */
-    buckets: Record<MediaKind, MediaBucketConfig>;
-    /** 是否启用 S3 Transfer Acceleration（对齐 Android，默认 true）。 */
+    /**
+     * 按**逻辑桶名**申请 S3 临时上传凭证；由宿主实现（打自己的 BFF），SDK 不硬编码接口路径与前缀。
+     * 缓存、TTL、同桶单飞与失败重签由本 adapter 负责，宿主实现应当是「打一次接口」的纯函数。
+     */
+    getUploadCredentials: MediaUploadCredentialsProvider;
+    /** 各媒体类型的**逻辑桶名**（宿主 env 配置，如 image→app-image）；物理桶以服务端回包为准。 */
+    buckets: Record<MediaKind, string>;
+    /**
+     * CHANNEL（社群）会话按媒体类型覆盖的逻辑桶名；未覆盖的类型继续使用 `buckets`。
+     * iOS 与 prod H5 都为社群媒体准备了独立桶，但对「社群文件是否也走社群桶」结论相反，
+     * 因此这里只提供按类型覆盖的机制，由部署配置决定覆盖哪些类型。
+     */
+    channelBuckets?: Partial<Record<MediaKind, string>>;
+    /** 群、社群与用户头像使用的独立 app-header 逻辑桶名；不得复用聊天图片桶。 */
+    avatarBucket?: string;
+    /** 是否启用 S3 Transfer Acceleration（默认 true；`cn-` 分区没有加速端点，会强制关闭）。 */
     useAccelerateEndpoint?: boolean;
+    /**
+     * 是否允许超过分片阈值（16MiB）的上传使用 S3 分片上传（默认 true）。
+     *
+     * 分片相比单次 PUT 需要各物理桶的 CORS 额外放行 POST（Create/CompleteMultipartUpload）、
+     * DELETE（AbortMultipartUpload）并 `ExposeHeaders: ETag`；未配齐时分片会直接失败。
+     * 部署可置 false 立即退回全量单次 PutObject（大文件回到单连接与整包内存的旧行为），无需发版。
+     */
+    multipartUpload?: boolean;
     /**
      * 媒体发送阶段的并发上限；由 im-core 消费，adapter 本身仍只负责单个上传任务。
      * 缺省为 4，允许 1-6；高并发会提高吞吐，也会增加文件加密的内存峰值。
@@ -5137,12 +5186,20 @@ interface ImSettingsApi {
 }
 
 /**
- * 媒体对象存储（S3）配置：由宿主注入的**部署基建配置**，SDK 不硬编码 bucket/身份池/host（配置归属宿主层，经 ImClientOptions.media 注入）。
- * 形状 = im-browser `MediaTransferAdapterConfig`：`identityPoolId` + 独立 `avatar` app-header 位置 + 各 `MediaKind`（image/video/voice/file/sticker）的 `{ bucket, host }` + 可选 `useAccelerateEndpoint`、`maxConcurrentUploads`。
- * 业务契约对齐 Android AWSUploadManager / CommonConstants.AWS（Cognito 匿名身份池直传、对象 public-read、Transfer Acceleration；见 研究Android图片消息实现.md §A.2）。
- * ⚠ 各 bucket 需在对象存储侧配置 CORS 允许本站 origin（含分片上传 POST/DELETE + ExposeHeaders ETag）；`identityPoolId` 前端可见（对齐 Android 现状）。
- * 并发字段只由 SDK core 的媒体编排消费；adapter 会忽略该字段。高内存设备可设置 5-6，低内存设备建议 2-3。
- * ⚠ 后续如需更安全（presigned URL）改 im-browser 的 `MediaTransferPort` 实现即可，本配置与调用方不变。
+ * 媒体对象存储（S3）配置：由宿主注入的**部署基建配置**，SDK 不硬编码逻辑桶名，也不硬编码取凭证的接口路径。
+ *
+ * 形状 = im-browser `MediaTransferAdapterConfig`：必填 `getUploadCredentials`（按逻辑桶名向宿主自己的 BFF 申请
+ * STS 临时凭证）+ 各 `MediaKind`（image/video/voice/file/sticker）的**逻辑桶名** + 可选 `channelBuckets`（社群会话
+ * 按类型覆盖）、`avatarBucket`、`useAccelerateEndpoint`、`multipartUpload`、`maxConcurrentUploads`。
+ *
+ * 上传凭证由业务后端按登录态签发（与 iOS、prod H5 同一个接口），回包同时给出**物理桶**、区域、`key_prefix` 和
+ * 公开访问域名；SDK 据此拼 object key 与消息体 URL，宿主 env 里配的只是申请凭证用的逻辑桶名。凭证缓存（本地
+ * 1 小时、按服务端过期时间提前 5 分钟失效）、同桶单飞与失败重签由 SDK 负责，宿主只需提供「打一次接口」的纯函数。
+ *
+ * ⚠ 各 bucket 需在对象存储侧配置 CORS 允许本站 origin 的 PUT + GET；超过 16MiB 的上传走 S3 分片，另需放行
+ * POST（Create/CompleteMultipartUpload）、DELETE（AbortMultipartUpload）并 ExposeHeaders: ETag。CORS 未配齐时
+ * 可用 `multipartUpload: false` 退回全量单次 PutObject。
+ * ⚠ 并发字段只由 SDK core 的媒体编排消费；adapter 会忽略该字段。高内存设备可设置 5-6，低内存设备建议 2-3。
  */
 type ImMediaConfig = MediaTransferAdapterConfig;
 /**