dsh-connect-trae 2.0.5 → 2.1.0

package/lib/index.d.ts

@@ -1156,6 +1156,21 @@ declare class TraeDelegatingUpstreamClient implements TraeUpstreamClient {
 declare const TRAE_PAY_BASE = "https://api.trae.cn";
 interface TraeUsageOptions {
   credential(): Promise<TraeCredential | undefined>;
+  /**
+   * Device identity of the credential's own installation, sent as
+   * `x-device-id` on the check-in routes.
+   *
+   * The claim endpoint is the one WRITE in this client, and it is guarded
+   * server-side by that header: with the same Authorization but no
+   * `x-device-id`, the upstream answers HTTP 200 with business code `9004`
+   * ("The submitted order parameters are incorrect") and grants nothing —
+   * verified 2026-09-24 against a live CN account, where adding the header
+   * flipped the same request to `code: 0` and the daily reward landed. The
+   * official client sends it on every check-in call
+   * (`main.js`'s `fb(headers)` sets `x-device-id` from `guaranteedDeviceId`).
+   * Absent, the client still reads status; only the claim refuses.
+   */
+  deviceId?(): Promise<string | undefined>;
   fetchImpl?: typeof fetch;
   baseUrl?: string;
   timeoutMs?: number;
@@ -1209,8 +1224,27 @@ interface TraeUsageSnapshot {
 }
 interface TraeCheckinStatus {
   checkedIn: boolean;
+  /** Reward for one check-in, as reported by the upstream (`credits`). */
   credits: number;
   enabled: boolean;
+  /**
+   * Whether today's reward was claimed in a previous session. The upstream
+   * reports `did_checked_in` separately from `checked_in`: the app uses the
+   * former to keep the claim button disabled for the rest of the Beijing day
+   * even when the status read happens to report `checked_in: false`.
+   */
+  didCheckedIn: boolean;
+  /** Bonus credit granted on top of the base reward, when the upstream reports one. */
+  extraCredits?: number;
+}
+/** Result of claiming today's check-in reward. */
+interface TraeCheckinClaim {
+  /** Whether the upstream accepted the claim (`code === 0`). */
+  claimed: boolean;
+  /** Business code from the answer; `0` on success. */
+  code: number;
+  /** Upstream message, verbatim but truncated — never token material. */
+  message: string;
 }
 interface TraeActivityRule {
   activityId: string;
@@ -1226,8 +1260,11 @@ interface TraeUsageView {
   activities: TraeActivityRule[];
 }
 /**
- * A read-only client for the verified Trae usage/credits endpoints.
- * All methods are safe to call from a plugin and never mutate account state.
+ * A client for the verified Trae usage/credits endpoints.
+ *
+ * Every method is read-only except {@link TraeUsageClient.claimCheckin}, which
+ * claims the daily check-in reward — the one deliberate mutation, requested by
+ * the user from the card and guarded before it is sent.
  */
 declare class TraeUsageClient {
   private readonly options;
@@ -1243,6 +1280,13 @@ declare class TraeUsageClient {
    * international region its own verified pay gateway.
    */
   private payBase;
+  /**
+   * Device id for the check-in routes, or undefined when the machine's
+   * installation identity cannot be read. Best-effort on purpose: a missing
+   * identity must not break the read-only status query, which the upstream
+   * answers with or without the header.
+   */
+  private deviceIdHeader;
   private authedHeaders;
   private post;
   /**
@@ -1260,8 +1304,26 @@ declare class TraeUsageClient {
   private requireCnRegion;
   /** Total entitlements / credits and per-pack breakdown. */
   snapshot(signal?: AbortSignal): Promise<TraeUsageSnapshot>;
-  /** Daily check-in status. */
+  /**
+   * Daily check-in status. Read-only, and answered with or without the device
+   * header — the claim is what needs it.
+   */
   checkinStatus(signal?: AbortSignal): Promise<TraeCheckinStatus>;
+  /**
+   * Claim today's check-in reward. The ONLY state-changing call in this client.
+   *
+   * The upstream is idempotent per Beijing day (verified 2026-09-24: repeating
+   * the call on an already-claimed day answers `code: 0` while the entitlement
+   * total stays byte-identical), so a double click cannot double-grant. The
+   * card and its route still guard, because "cannot double-grant" is a property
+   * of the upstream we verify rather than one we rely on.
+   *
+   * A business refusal arrives as HTTP 200 with a non-zero `code` — most often
+   * `9004` when the request carries no `x-device-id`. That is reported as
+   * `claimed: false` rather than thrown, so the caller can tell "the upstream
+   * refused this" apart from "the request never arrived".
+   */
+  claimCheckin(signal?: AbortSignal): Promise<TraeCheckinClaim>;
   /** Rewards / activity rules. */
   activities(signal?: AbortSignal): Promise<TraeActivityRule[]>;
   /** Convenience: snapshot + check-in + activities in one call (best-effort, non-fatal on missing). */
@@ -1271,6 +1333,11 @@ declare class TraeUsageClient {
 //#region src/status-paths.d.ts
 /** Plugin-owned usage endpoint consumed by its browser half. */
 declare const TRAE_USAGE_PATH = "/plugins/dsh-connect-trae/usage";
+/**
+ * Plugin-owned daily check-in claim endpoint. POST, loopback-only, and the only
+ * route in this plugin that changes upstream account state.
+ */
+declare const TRAE_CHECKIN_PATH = "/plugins/dsh-connect-trae/checkin";
 /** Query parameter naming the region a card request addresses. */
 declare const TRAE_REGION_PARAM = "region";
 /** Every region, in card tab order. */
@@ -1316,10 +1383,32 @@ interface TraeWebModel {
   };
   maxContextWindow?: number;
 }
-/** Daily check-in status rendered by the card. */
+/**
+ * Daily check-in state rendered below the credit stats.
+ *
+ * `didCheckedIn` is not redundant with `checkedIn`: the upstream reports them
+ * separately, and the official client keeps the claim button disabled for the
+ * rest of the Beijing day off `did_checked_in` even when a status read comes
+ * back `checked_in: false`. The card mirrors that rule so a stale-looking
+ * status cannot invite a pointless second claim.
+ */
 interface TraeWebCheckin {
   checkedIn: boolean;
+  didCheckedIn: boolean;
   credits: number;
+  enabled: boolean;
+  extraCredits?: number;
+}
+/** The claim route's answer, so the card can report a business refusal verbatim. */
+interface TraeWebCheckinClaim {
+  /** False when the upstream answered a non-zero business code (e.g. 9004). */
+  claimed: boolean;
+  /** True when today was already claimed, so nothing was sent upstream. */
+  alreadyCheckedIn: boolean;
+  code?: number;
+  message?: string;
+  /** The refreshed check-in state, present whenever the claim path ran. */
+  checkin?: TraeWebCheckin;
 }
 /** One reward activity rule (name + work/general credits when present). */
 interface TraeWebActivity {
@@ -1346,6 +1435,42 @@ interface TraeWebSearchPath {
   reason: 'missing' | 'unreadable' | 'invalid';
   message?: string;
 }
+/**
+ * Build the next `regions` settings value for the card's save. The write
+ * targets ONLY the signed-in account's region slot; every other region's slot
+ * is carried over untouched, so switching accounts never clobbers the other
+ * region's picks. Tolerates any stored shape (absent, non-object) by starting
+ * from an empty document.
+ */
+declare function nextRegionSlots<Slot extends object>(regions: unknown, region: TraeRegion, slot: Slot): Record<string, unknown>;
+/**
+ * Whether one region's provider is switched on. Opt-out semantics: only an
+ * explicit `false` disables it, so a config written before this switch existed
+ * (and the pre-region-split flat fields, which never carry `enabled`) keep both
+ * providers running exactly as before. The Host reads the same rule through
+ * `regionStateOf`, so card and Host can never disagree about a region's state.
+ *
+ * `value` may be the whole settings section or the `regions` map (see
+ * {@link regionsMapOf}).
+ */
+declare function regionEnabledOf(value: unknown, region: TraeRegion): boolean;
+/**
+ * Build the next `regions` settings value for a provider on/off toggle. ONLY
+ * the target region's `enabled` flag changes: every other field of that slot
+ * (its directory, selection, image opt-ins, context budgets) and every other
+ * region's slot are carried over verbatim, so switching a provider off never
+ * discards the user's model picks and switching it back on restores them.
+ *
+ * This is deliberately separate from {@link nextRegionSlots}: that helper
+ * writes a whole slot from a signed-in tab's draft, while this one must work
+ * for a region that is signed OUT — which is precisely the region a user wants
+ * to switch off (no international install, no international account).
+ *
+ * `value` may be the whole settings section or the `regions` map; the RETURN
+ * value is always the `regions` map, i.e. exactly what `settingsScope.set(
+ * 'regions', ...)` needs.
+ */
+declare function nextRegionEnabled(value: unknown, region: TraeRegion, enabled: boolean): Record<string, unknown>;
 /** Subscription status of an international (ai) account, rendered instead of the CN credit packs. */
 interface TraeWebPayStatus {
   isDollarUsageBilling: boolean;
@@ -1369,6 +1494,7 @@ type TraeWebUsage = {
   accounts: readonly TraeWebAccount[];
   message?: string;
   searched?: readonly TraeWebSearchPath[];
+  enabled?: boolean;
 } | {
   status: 'signed-in';
   accountId: string;
@@ -1376,6 +1502,8 @@ type TraeWebUsage = {
   tokenExpiresAtMs: number;
   /** Which per-region model directory and selection this account owns. */
   region: TraeRegion;
+  /** Whether this region's provider is currently offered to DSH. */
+  enabled?: boolean;
   accounts: readonly TraeWebAccount[];
   models: readonly TraeWebModel[];
   enabledModelIds: readonly string[];
@@ -1386,6 +1514,14 @@ type TraeWebUsage = {
   };
   credits?: TraeWebCredits;
   creditsError?: string;
+  /**
+   * Daily check-in state (CN only). Absent on the international region,
+   * whose check-in surface does not exist — probed 2026-09-24: the
+   * `/trae/api/v2/ug/*` family answers 404 on every ai gateway, so the card
+   * shows no claim button there rather than a button that cannot work.
+   */
+  checkin?: TraeWebCheckin;
+  checkinError?: string;
   /** Subscription status of an international account (region ai only). */
   payStatus?: TraeWebPayStatus;
   payStatusError?: string;
@@ -1410,6 +1546,12 @@ interface TraeUsageRouteOptions {
   displayModels(region: TraeRegion): readonly TraeModelInfo[];
   /** The user's model selection in the requested region, stored as model id (= Trae name). */
   enabledModelIds(region: TraeRegion): readonly string[];
+  /**
+   * Whether the requested region's provider is currently offered to DSH. The
+   * card renders this as the tab's on/off checkbox, so the switch reflects the
+   * committed settings value rather than a local guess.
+   */
+  regionEnabled(region: TraeRegion): boolean;
   /** Re-read one region's live directory from the upstream. */
   discoverModels?(region: TraeRegion, signal?: AbortSignal): Promise<readonly TraeModelInfo[]>;
   /** Raw-Chat capability state of the requested region. */
@@ -1440,6 +1582,15 @@ declare const inject: string[];
 declare const TRAE_SETTINGS_NS = "trae";
 /** One region's saved model state: its own directory and the user's selection within it. */
 interface TraeRegionState {
+  /**
+   * Whether this region's provider is switched on. Opt-out: only an explicit
+   * `false` disables it, so a config predating this switch keeps both providers
+   * running. A disabled region is fully withdrawn from the harness — its
+   * adapter route and its configurable-provider entry both hold zero routes, so
+   * it disappears from DSH's model picker instead of lingering as an
+   * unselectable row (see `syncRegionRegistration`).
+   */
+  enabled?: boolean;
   /** The last-refreshed raw directory for this region; what the card displays. */
   lastCatalog?: TraeModelInfo[];
   /** The user's selection in this region, as model ids (= Trae name). */
@@ -1495,7 +1646,16 @@ interface Config {
  * picks (the same failure workbuddy fixed with its region split).
  */
 declare function regionStateOf(config: Config, region: TraeRegion): TraeRegionState;
+/**
+ * Whether one region's provider is switched on (issue #11). Opt-out semantics:
+ * only an explicit `false` disables it, so every config written before this
+ * switch existed — including the pre-region-split flat fields, which never
+ * carry `enabled` — keeps both providers running exactly as before. The card
+ * reads the same rule through `regionEnabledOf`, so the two halves can never
+ * disagree about a region's state.
+ */
+declare function regionEnabled(config: Config, region: TraeRegion): boolean;
 declare const Config: z<Config>;
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { Config, FALLBACK_TRAE_MODELS, FALLBACK_TRAE_MODELS_AI, REGION_GATEWAYS, type RawChatDelta, type RawChatMessage, type RawChatTool, SseDecoder, type SseEvent, TRAE_AI_PROVIDER, TRAE_CN_AGENT_TASK_PATH, TRAE_CN_TITLE_PATH, TRAE_MODEL_DETAIL_FUNCTIONS, TRAE_MODEL_DETAIL_PATH, TRAE_PAY_BASE, TRAE_PROVIDER, TRAE_PROVIDERS, TRAE_PROVIDER_DISPLAY_NAMES, TRAE_RAW_CHAT_V1_PATH, TRAE_RAW_CHAT_V2_PATH, TRAE_REASONING_EFFORTS, TRAE_REGIONS, TRAE_REGION_PARAM, TRAE_SETTINGS_NS, TRAE_SOLO_CHAT_PATH, TRAE_SOLO_FUNCTION, TRAE_SOLO_MODELS_PATH, TRAE_SOLO_REMOTE_BASE, TRAE_STREAM_IDLE_TIMEOUT_MS, TRAE_USAGE_PATH, TRAE_VERSION_CODE_FALLBACK, type TraeActivityRule, type TraeAdapter, type TraeCachedModelConfig, TraeCatalog, type TraeChatResult, type TraeCheckinStatus, type TraeContextBudget, type TraeCredential, TraeCredentialStore, TraeDelegatingUpstreamClient, type TraeDiscoveredModel, type TraeDiscoveredReasoning, type TraeEdition, TraeFallbackUpstreamClient, type TraeFallbackUpstreamOptions, type TraeFusionRawChatEnvelope, TraeGatedUpstreamClient, type TraeGatedUpstreamOptions, type TraeIdentity, type TraeInputModality, type TraeModelDetailRequest, type TraeModelInfo, type TraeObservedModelConfig, TraeRawCapabilityController, type TraeRawCapabilityControllerOptions, type TraeRawCapabilitySnapshot, TraeRawCapabilityState, type TraeRawChatBehaviorConfig, type TraeRawChatCapability, type TraeRawChatClientOptions, type TraeRawChatConfig, type TraeRawChatFailureReason, type TraeRawChatRuntimeConfig, TraeRawChatUpstreamClient, type TraeRawDiagnostic, type TraeRawDiagnosticState, type TraeRawGateway, type TraeRawGatewayOptions, type TraeRawResolverResult, type TraeReasoningCapability, type TraeReasoningEffort, type TraeRefreshDevice, type TraeRegion, type TraeRegionGateways, TraeRegionState, type TraeShim, TraeSoloBridge, type TraeSoloClientOptions, TraeSoloRemoteCatalogClient, type TraeSoloRemoteCatalogOptions, TraeSoloUpstreamClient, type TraeStorageCandidate, type TraeStreamEvent, type TraeUpstreamClient, TraeUsageClient, type TraeUsageOptions, type TraeUsagePack, type TraeUsageRouteOptions, type TraeUsageSnapshot, type TraeUsageSummary, type TraeUsageView, type TraeWebActivity, type TraeWebCheckin, type TraeWebCredits, type TraeWebUsage, type TraeWireModel, UnconfiguredTraeUpstreamClient, apply, applyContextBudgets, applyImageSelection, applyReasoningEffort, bridgeTraeSoloStream, buildTraeAgentTaskBody, buildTraeCnHeaders, buildTraeFusionRawChatEnvelope, buildTraeModelDetailRequest, buildTraeRawChatDraft, buildTraeRawChatRuntimeConfig, classifyTraeRawChatFailure, createTraeAdapter, createTraeRawGateway, createTraeShim, decodeRawChatChunk, decodeTraeEvent, decryptTraeStorageValue, deriveCatalog, discoveredCatalog, fallbackModelsFor, hashTraeRawChatArg, identityHeaders, inject, legacyTraeOwnAuthPath, mergeTraeModelSources, name, normalizeTraeCredential, normalizeTraeVersionCode, parseObservedModelConfig, parseReasoningCapability, parseTraeAuthValue, parseTraeCachedModel, parseTraeModelExtraConfigLogLine, parseTraeRawChatBehaviorConfig, parseTraeRemoteModel, parseTraeStorageDocument, pickTraeStorageIdentity, prepareSoloBody, probeTraeRawChatCapability, rawCapabilityDiagnostic, rawCapabilityFingerprint, readTraeCachedModel, readTraeCliIdentity, readTraeIdentity, refreshTraeCredential, regionOfCredential, regionOfEdition, regionOfHost, regionOfTraeProvider, regionOfTraeStatusUrl, regionOfUserRegion, regionStateOf, registerTraeUsageRoute, resolveTraeIdentity, resolveTraeRawRuntime, sanitizeCatalog, traeEndpoint, traeInputModalities, traeModelDisplayName, traeOwnAuthPath, traeRawChatExtraInfo, traeStorageCandidates, traeWebUsage, withTraeRegion };
+export { Config, FALLBACK_TRAE_MODELS, FALLBACK_TRAE_MODELS_AI, REGION_GATEWAYS, type RawChatDelta, type RawChatMessage, type RawChatTool, SseDecoder, type SseEvent, TRAE_AI_PROVIDER, TRAE_CHECKIN_PATH, TRAE_CN_AGENT_TASK_PATH, TRAE_CN_TITLE_PATH, TRAE_MODEL_DETAIL_FUNCTIONS, TRAE_MODEL_DETAIL_PATH, TRAE_PAY_BASE, TRAE_PROVIDER, TRAE_PROVIDERS, TRAE_PROVIDER_DISPLAY_NAMES, TRAE_RAW_CHAT_V1_PATH, TRAE_RAW_CHAT_V2_PATH, TRAE_REASONING_EFFORTS, TRAE_REGIONS, TRAE_REGION_PARAM, TRAE_SETTINGS_NS, TRAE_SOLO_CHAT_PATH, TRAE_SOLO_FUNCTION, TRAE_SOLO_MODELS_PATH, TRAE_SOLO_REMOTE_BASE, TRAE_STREAM_IDLE_TIMEOUT_MS, TRAE_USAGE_PATH, TRAE_VERSION_CODE_FALLBACK, type TraeActivityRule, type TraeAdapter, type TraeCachedModelConfig, TraeCatalog, type TraeChatResult, type TraeCheckinClaim, type TraeCheckinStatus, type TraeContextBudget, type TraeCredential, TraeCredentialStore, TraeDelegatingUpstreamClient, type TraeDiscoveredModel, type TraeDiscoveredReasoning, type TraeEdition, TraeFallbackUpstreamClient, type TraeFallbackUpstreamOptions, type TraeFusionRawChatEnvelope, TraeGatedUpstreamClient, type TraeGatedUpstreamOptions, type TraeIdentity, type TraeInputModality, type TraeModelDetailRequest, type TraeModelInfo, type TraeObservedModelConfig, TraeRawCapabilityController, type TraeRawCapabilityControllerOptions, type TraeRawCapabilitySnapshot, TraeRawCapabilityState, type TraeRawChatBehaviorConfig, type TraeRawChatCapability, type TraeRawChatClientOptions, type TraeRawChatConfig, type TraeRawChatFailureReason, type TraeRawChatRuntimeConfig, TraeRawChatUpstreamClient, type TraeRawDiagnostic, type TraeRawDiagnosticState, type TraeRawGateway, type TraeRawGatewayOptions, type TraeRawResolverResult, type TraeReasoningCapability, type TraeReasoningEffort, type TraeRefreshDevice, type TraeRegion, type TraeRegionGateways, TraeRegionState, type TraeShim, TraeSoloBridge, type TraeSoloClientOptions, TraeSoloRemoteCatalogClient, type TraeSoloRemoteCatalogOptions, TraeSoloUpstreamClient, type TraeStorageCandidate, type TraeStreamEvent, type TraeUpstreamClient, TraeUsageClient, type TraeUsageOptions, type TraeUsagePack, type TraeUsageRouteOptions, type TraeUsageSnapshot, type TraeUsageSummary, type TraeUsageView, type TraeWebActivity, type TraeWebCheckin, type TraeWebCheckinClaim, type TraeWebCredits, type TraeWebUsage, type TraeWireModel, UnconfiguredTraeUpstreamClient, apply, applyContextBudgets, applyImageSelection, applyReasoningEffort, bridgeTraeSoloStream, buildTraeAgentTaskBody, buildTraeCnHeaders, buildTraeFusionRawChatEnvelope, buildTraeModelDetailRequest, buildTraeRawChatDraft, buildTraeRawChatRuntimeConfig, classifyTraeRawChatFailure, createTraeAdapter, createTraeRawGateway, createTraeShim, decodeRawChatChunk, decodeTraeEvent, decryptTraeStorageValue, deriveCatalog, discoveredCatalog, fallbackModelsFor, hashTraeRawChatArg, identityHeaders, inject, legacyTraeOwnAuthPath, mergeTraeModelSources, name, nextRegionEnabled, nextRegionSlots, normalizeTraeCredential, normalizeTraeVersionCode, parseObservedModelConfig, parseReasoningCapability, parseTraeAuthValue, parseTraeCachedModel, parseTraeModelExtraConfigLogLine, parseTraeRawChatBehaviorConfig, parseTraeRemoteModel, parseTraeStorageDocument, pickTraeStorageIdentity, prepareSoloBody, probeTraeRawChatCapability, rawCapabilityDiagnostic, rawCapabilityFingerprint, readTraeCachedModel, readTraeCliIdentity, readTraeIdentity, refreshTraeCredential, regionEnabled, regionEnabledOf, regionOfCredential, regionOfEdition, regionOfHost, regionOfTraeProvider, regionOfTraeStatusUrl, regionOfUserRegion, regionStateOf, registerTraeUsageRoute, resolveTraeIdentity, resolveTraeRawRuntime, sanitizeCatalog, traeEndpoint, traeInputModalities, traeModelDisplayName, traeOwnAuthPath, traeRawChatExtraInfo, traeStorageCandidates, traeWebUsage, withTraeRegion };