@eddyskywalker/dsh-chatgpt-subscription 0.40.1 → 0.40.2

package/lib/types/host/kimi-code/media-files.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Kimi Code hosted-file (media upload) client.
+ *
+ * WHY THIS FILE EXISTS. Everything this plugin has ever sent to the Kimi Code
+ * gateway carries media INLINE, as a `data:<type>;base64,...` URL
+ * (mapper.ts builds both the image and the video block that way). The gateway
+ * also accepts a hosted reference instead: upload the bytes once, cite
+ * `ms://<id>` afterwards. That is the only way to send a clip whose base64 would
+ * overrun the request body ceiling, and it is what this module implements.
+ *
+ * EVERY WIRE FACT BELOW WAS MEASURED live against the subscription gateway by
+ * `scripts/probe-kimi-files.probe.ts` on this line's own account and region,
+ * not copied from the official client:
+ *
+ * - the upload is `POST {coding base}/v1/files`, `multipart/form-data` with a
+ *   `file` part and a `purpose` part whose value is `image` or `video`
+ *   (note: NOT the `*_understanding` vocabulary the MiniMax line uses);
+ * - it authenticates with the bearer token plus the same `X-Msh-*` identity
+ *   headers every other request on this line sends;
+ * - the body answers with the id at the top level or nested under
+ *   `data`/`file`/`result`, and the reference a later chat body cites is
+ *   `ms://<id>`;
+ * - `content-type` is never set by hand: the runtime writes
+ *   `multipart/form-data; boundary=...` itself, and a hand-written JSON header
+ *   on a form body is a malformed request.
+ *
+ * DELIBERATELY NARROW. No adapter, mapper or route is touched here: this module
+ * only uploads, caches and returns a reference. Integration is a later change.
+ *
+ * @module dsh-chatgpt-subscription/kimi-media-files
+ */
+/** Upload route, relative to a base URL that may already carry `/v1`. */
+export declare const FILES_UPLOAD_PATH = "/v1/files";
+/** Scheme a stored id is cited by on the wire. */
+export declare const FILE_REF_SCHEME = "ms://";
+/**
+ * Ceiling on cached references.
+ *
+ * Bounded because a long conversation can attach many distinct clips and a
+ * process that lives for days must not grow one map per upload forever. 256 is
+ * far more than one conversation cites and small enough to be invisible.
+ */
+export declare const DEFAULT_MEDIA_FILE_CACHE_ENTRIES = 256;
+/** Time budget for one upload request. */
+export declare const MEDIA_UPLOAD_TIMEOUT_MS = 120000;
+/** The two purposes this surface measuredly accepts. */
+export type KimiMediaKind = 'image' | 'video';
+/** Why one upload could not produce a usable reference. */
+export type KimiMediaUploadFailure = 
+/** The request was unusable before anything was sent (media type, empty body, ...). */
+'invalid-request'
+/** The media type is not image/* or video/*, so there is no purpose to send. */
+ | 'unsupported-media'
+/** HTTP 401/403: the credential was not accepted. */
+ | 'unauthorized'
+/** HTTP 404/405: this base URL does not expose the upload route. */
+ | 'not-found'
+/** HTTP 413: the service refused the body as too large. */
+ | 'too-large'
+/** HTTP 5xx: the service failed; the same request may succeed later. */
+ | 'server'
+/** Any other non-2xx answer. */
+ | 'rejected'
+/** 2xx whose body was not JSON. */
+ | 'not-json'
+/** 2xx whose body carried no usable id. */
+ | 'no-id'
+/** The local time budget elapsed before the response arrived. */
+ | 'timeout'
+/** The request never completed (socket, DNS, TLS, ...). */
+ | 'network';
+/**
+ * One failed upload.
+ *
+ * Carries the HTTP status and a REDACTED digest of the response body so a
+ * caller can decide (401 -> sign in again, 5xx -> retry) without the raw body
+ * reaching a log. The access token is never placed in `message` or `detail`;
+ * see {@link redact}.
+ */
+export declare class KimiMediaUploadError extends Error {
+    readonly failure: KimiMediaUploadFailure;
+    readonly status: number | null;
+    /** Redacted one-line digest of the response body, or '' when there was none. */
+    readonly detail: string;
+    constructor(failure: KimiMediaUploadFailure, message: string, options?: {
+        status?: number | null;
+        detail?: string;
+    });
+}
+/** What one upload needs. */
+export interface KimiMediaUploadRequest {
+    /** Bearer token the caller obtained; never logged and never part of a key. */
+    readonly accessToken: string;
+    /** Coding API base, with or without a trailing slash and with or without `/v1`. */
+    readonly baseUrl: string;
+    /**
+     * Opaque, stable identifier of the ACCOUNT the bytes are uploaded under.
+     *
+     * It scopes the cache: an id minted for one account is never handed to
+     * another, because nothing here proves the gateway shares ids across accounts.
+     * It must identify the account (a user id, an account slot index) and must
+     * NEVER be the access token — {@link KimiMediaFilesUploader.upload} refuses
+     * that, so a token cannot end up inside a cache key by accident.
+     */
+    readonly accountScope: string;
+    /** Complete file bytes. */
+    readonly data: Uint8Array;
+    /** Media type, such as `image/png` or `video/mp4`. */
+    readonly mediaType: string;
+    /** Optional display name; only its leaf is used, and never as a path. */
+    readonly filename?: string;
+    /** Cancels this caller's wait, and the upload once nobody is waiting. */
+    readonly signal?: AbortSignal;
+}
+/** Everything a caller of this module may swap out, plus test seams. */
+export interface KimiMediaUploadOptions {
+    /** Transport; defaults to the global `fetch`. */
+    readonly fetchFn?: typeof fetch;
+    /** Cache ceiling; defaults to {@link DEFAULT_MEDIA_FILE_CACHE_ENTRIES}. */
+    readonly maxCacheEntries?: number;
+    /** Per-request time budget; 0 (or a negative value) disables it. */
+    readonly timeoutMs?: number;
+}
+/**
+ * The upload URL for one coding base.
+ *
+ * The base this line resolves normally carries neither a version nor a trailing
+ * slash (`https://api.kimi.com/coding`), so the measured route is built by
+ * appending `/v1/files` and the answer is `.../coding/v1/files`. A caller that
+ * passes a base which ALREADY ends in `/v1` — the official client's own
+ * KIMI_CODE_BASE_URL shape — gets the prefix removed once rather than doubled:
+ * `.../coding/v1/v1/files` is a 404 that reads like a missing route.
+ */
+export declare function filesUploadUrl(baseUrl: string): string;
+/** The upload purpose one media type maps to, or undefined when unsupported. */
+export declare function mediaKindFor(mediaType: string): KimiMediaKind | undefined;
+/** The wire reference for a stored id. */
+export declare function fileReference(id: string): string;
+/**
+ * The cache key for one upload.
+ *
+ * Five things, and each of them is load-bearing:
+ *
+ * - ACCOUNT SCOPE, because an id minted for one account is never assumed to be
+ *   readable by another (see {@link KimiMediaUploadRequest.accountScope});
+ * - BASE URL (normalized through {@link filesUploadUrl}, so a trailing slash
+ *   cannot split one endpoint into two slots), because two regions or two
+ *   deployments are two distinct file stores;
+ * - MEDIA KIND and MEDIA TYPE, because the same bytes uploaded as an image and
+ *   as a video are two different resources as far as the purpose is concerned;
+ * - CONTENT SHA-256, so identical bytes reuse one upload and any change at all
+ *   misses the cache.
+ *
+ * The access token is NOT part of it: a key is written to memory only, but a
+ * token in a key is a token in the next dump, and the account is already
+ * identified by its scope. `|` cannot appear in a scope because the scope is
+ * sanitized here.
+ */
+export declare function mediaFileCacheKey(input: {
+    accountScope: string;
+    baseUrl: string;
+    mediaType: string;
+    data: Uint8Array;
+}): string;
+/**
+ * Uploads one media file per distinct key, caching and single-flighting them.
+ *
+ * Two behaviours are deliberate and easy to get wrong:
+ *
+ * 1. SINGLE FLIGHT. Concurrent callers with the same key share one request.
+ *    A caller that aborts stops waiting immediately and gets an AbortError, but
+ *    the shared request is only cancelled once NO caller is still waiting — so
+ *    one cancelled turn does not fail another turn that wants the same clip.
+ * 2. NO TTL. A successful reference is cached until it is evicted by the LRU
+ *    ceiling. Inventing an expiry would either expire a live id (a failed turn)
+ *    or outlive it silently; nothing here measured a lifetime, so nothing here
+ *    pretends to know one. A reference the service later rejects is dropped with
+ *    {@link forget} by whoever sees that rejection.
+ */
+export declare class KimiMediaFilesUploader {
+    private readonly fetchFn;
+    private readonly maxCacheEntries;
+    private readonly timeoutMs;
+    /** key -> `ms://<id>`, in least-recently-used order. */
+    private readonly cache;
+    private readonly flights;
+    constructor(options?: KimiMediaUploadOptions);
+    /** Cached references currently held, for a settings surface or a test. */
+    get size(): number;
+    /** Uploads one file and returns the `ms://<id>` reference a request cites. */
+    upload(request: KimiMediaUploadRequest): Promise<string>;
+    /**
+     * Drop the reference one upload would use.
+     *
+     * The caller that sees a stored id REJECTED on the wire calls this so the next
+     * attempt uploads again instead of replaying the same dead reference.
+     */
+    forget(request: Omit<KimiMediaUploadRequest, 'accessToken'>): boolean;
+    /** Forget everything; a sign-out or a test starting over. */
+    clear(): void;
+    /** Validate and normalize one request, or throw before anything is sent. */
+    private resolve;
+    private readCache;
+    private writeCache;
+    /** Open one flight and run it; the map entry is dropped as it settles. */
+    private startFlight;
+    /**
+     * Wait for one flight, respecting THIS caller's abort.
+     *
+     * The flight is not bound to the caller's signal: a caller that aborts
+     * detaches, and the transport is cancelled only when the last waiter has gone.
+     */
+    private join;
+    /** The one request a flight performs. */
+    private performUpload;
+    /** Turn a transport rejection into the error the caller must see. */
+    private transportFailure;
+    /** Read one response into a reference, or into a typed failure. */
+    private settle;
+}
+/** One uploader with the default transport and cache size. */
+export declare function createMediaFilesUploader(options?: KimiMediaUploadOptions): KimiMediaFilesUploader;
+/**
+ * The process-wide uploader the adapter will use.
+ *
+ * Shared on purpose: the cache is the whole point, and a per-call instance would
+ * upload the same clip once per turn.
+ */
+export declare const kimiMediaFiles: KimiMediaFilesUploader;
+/** Upload one file through the shared uploader. */
+export declare function uploadMediaFile(request: KimiMediaUploadRequest): Promise<string>;
+//# sourceMappingURL=media-files.d.ts.map

package/lib/types/host/kimi-code/media-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-files.d.ts","sourceRoot":"","sources":["../../../../src/host/kimi-code/media-files.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eddyskywalker/dsh-chatgpt-subscription",
-  "version": "0.40.1",
+  "version": "0.40.2",
   "description": "DSH provider plugin for Codex access through a ChatGPT subscription.",
   "icon": "./icon.svg",
   "author": {