@native-marketing/sdk 0.3.6 → 0.3.7

package/package.json

@@ -1,11 +1,21 @@
 {
   "name": "@native-marketing/sdk",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "type": "module",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=24 <25"
   },
+  "nativeMarketing": {
+    "contractVersion": 1,
+    "apiMajor": 1,
+    "nodeMajor": 24,
+    "changes": [
+      "Unified SDK, CLI and MCP release discovery and compatibility checks.",
+      "Configurable CLI update notifications, pins and compatible automatic updates.",
+      "Upgrade verification and explicit continuation without replaying business commands."
+    ]
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/release.json

@@ -1,7 +1,7 @@
 {
-  "sourceCommit": "40463e01d4112b05570b24ec7da538ed5f489d0d",
+  "sourceCommit": "170f43ed793abd2cee15faaba49428aa43c276cd",
   "workingTreeDirty": false,
-  "version": "0.3.6",
+  "version": "0.3.7",
   "openapiTypesSha256": "e79e0abf034cae01174e67464aea55f16d40895c86199eff93897ec892ea82f4",
   "localBuild": true
 }

package/types/contracts/client-lifecycle.d.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+export { nativeClientRelease } from './generated/client-release.js';
+export declare const nativeReleaseCapability = "com.native-marketing/client-release";
+export declare const releaseVersionSchema: z.ZodString;
+export declare const clientIdentitySchema: z.ZodObject<{
+    version: z.ZodString;
+    contractVersion: z.ZodNumber;
+    apiMajor: z.ZodNumber;
+}, z.core.$strip>;
+export declare const clientReleaseSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    product: z.ZodLiteral<"native-marketing">;
+    version: z.ZodString;
+    packages: z.ZodObject<{
+        sdk: z.ZodLiteral<"@native-marketing/sdk">;
+        cli: z.ZodLiteral<"@native-marketing/cli">;
+    }, z.core.$strip>;
+    contractVersion: z.ZodNumber;
+    minimumClientVersion: z.ZodString;
+    apiMajor: z.ZodNumber;
+    nodeMajor: z.ZodNumber;
+    changes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const updatePolicySchema: z.ZodObject<{
+    mode: z.ZodDefault<z.ZodEnum<{
+        auto: "auto";
+        notify: "notify";
+        off: "off";
+    }>>;
+    channel: z.ZodDefault<z.ZodEnum<{
+        beta: "beta";
+        latest: "latest";
+        next: "next";
+    }>>;
+    pin: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    intervalHours: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const defaultUpdatePolicy: {
+    mode: "auto" | "notify" | "off";
+    channel: "beta" | "latest" | "next";
+    pin: string | null;
+    intervalHours: number;
+};
+export type NativeClientIdentity = z.infer<typeof clientIdentitySchema>;
+export type NativeClientRelease = z.infer<typeof clientReleaseSchema>;
+export type NativeUpdatePolicy = z.infer<typeof updatePolicySchema>;
+export interface NativeCompatibility {
+    status: 'COMPATIBLE' | 'UPGRADE_RECOMMENDED' | 'INCOMPATIBLE' | 'UNKNOWN';
+    reason: 'CURRENT' | 'NEWER_CLIENT_AVAILABLE' | 'CLIENT_TOO_OLD' | 'CONTRACT_MISMATCH' | 'API_MISMATCH' | 'SERVER_METADATA_UNAVAILABLE';
+    client: NativeClientIdentity;
+    server: NativeClientRelease | null;
+}
+/** Exact SemVer precedence only; package-manager ranges are never interpreted here. */
+export declare function compareReleaseVersions(left: string, right: string): number;
+export declare function assessNativeCompatibility(client: NativeClientIdentity, server?: NativeClientRelease): NativeCompatibility;

package/types/contracts/client-update-policy.d.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { type NativeClientRelease, type NativeUpdatePolicy } from './client-lifecycle.js';
+export declare const registryReleaseSchema: z.ZodObject<{
+    name: z.ZodEnum<{
+        "@native-marketing/cli": "@native-marketing/cli";
+        "@native-marketing/sdk": "@native-marketing/sdk";
+    }>;
+    version: z.ZodString;
+    deprecated: z.ZodOptional<z.ZodString>;
+    nativeMarketing: z.ZodOptional<z.ZodObject<{
+        contractVersion: z.ZodNumber;
+        apiMajor: z.ZodNumber;
+        nodeMajor: z.ZodNumber;
+        changes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    dist: z.ZodObject<{
+        integrity: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type NativeRegistryRelease = z.infer<typeof registryReleaseSchema>;
+export declare const clientUpdateStateSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    policy: z.ZodObject<{
+        mode: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            notify: "notify";
+            off: "off";
+        }>>;
+        channel: z.ZodDefault<z.ZodEnum<{
+            beta: "beta";
+            latest: "latest";
+            next: "next";
+        }>>;
+        pin: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        intervalHours: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    lastCheck: z.ZodOptional<z.ZodObject<{
+        at: z.ZodNumber;
+        selector: z.ZodString;
+        target: z.ZodObject<{
+            name: z.ZodEnum<{
+                "@native-marketing/cli": "@native-marketing/cli";
+                "@native-marketing/sdk": "@native-marketing/sdk";
+            }>;
+            version: z.ZodString;
+            deprecated: z.ZodOptional<z.ZodString>;
+            nativeMarketing: z.ZodOptional<z.ZodObject<{
+                contractVersion: z.ZodNumber;
+                apiMajor: z.ZodNumber;
+                nodeMajor: z.ZodNumber;
+                changes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+            dist: z.ZodObject<{
+                integrity: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, z.core.$strict>>;
+    lastAttempt: z.ZodOptional<z.ZodObject<{
+        at: z.ZodNumber;
+        selector: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type NativeClientUpdateState = z.infer<typeof clientUpdateStateSchema>;
+export interface NativeUpdatePlan {
+    package: NativeRegistryRelease['name'];
+    currentVersion: string;
+    targetVersion: string;
+    status: 'CURRENT' | 'UPDATE_AVAILABLE' | 'BLOCKED';
+    reason: 'CURRENT' | 'COMPATIBLE_UPDATE' | 'REVIEW_REQUIRED' | 'PIN_MISMATCH' | 'CHANNEL_MISMATCH' | 'DOWNGRADE_FORBIDDEN' | 'METADATA_UNAVAILABLE' | 'CONTRACT_MISMATCH' | 'NODE_MISMATCH' | 'SERVER_INCOMPATIBLE' | 'DEPRECATED';
+    eligibleForAutoUpdate: boolean;
+    policy: NativeUpdatePolicy;
+    commands: {
+        npm: string[];
+        pnpm: string[];
+        yarn: string[] | null;
+    };
+}
+export declare function planNativeUpdate(input: {
+    target: NativeRegistryRelease;
+    currentVersion?: string;
+    policy?: NativeUpdatePolicy;
+    nodeMajor?: number;
+    server?: NativeClientRelease;
+}): NativeUpdatePlan;

package/types/contracts/generated/client-release.d.ts

@@ -0,0 +1,14 @@
+export declare const nativeClientRelease: {
+    readonly schemaVersion: 1;
+    readonly product: 'native-marketing';
+    readonly version: '0.3.7';
+    readonly packages: {
+        readonly sdk: '@native-marketing/sdk';
+        readonly cli: '@native-marketing/cli';
+    };
+    readonly contractVersion: 1;
+    readonly minimumClientVersion: '0.3.6';
+    readonly apiMajor: 1;
+    readonly nodeMajor: 24;
+    readonly changes: readonly ['Unified SDK, CLI and MCP release discovery and compatibility checks.', 'Configurable CLI update notifications, pins and compatible automatic updates.', 'Upgrade verification and explicit continuation without replaying business commands.'];
+};

package/types/contracts/index.d.ts

@@ -117,3 +117,5 @@ export * from './event-backlog.js';
 export * from './event-readiness.js';
 export * from './event-inbox.js';
 export * from './event-outbox-browser.js';
+export * from './client-lifecycle.js';
+export * from './client-update-policy.js';

package/types/http/client-version.d.ts

@@ -0,0 +1,35 @@
+import type { ContentFactoryClientOptions } from './client.js';
+export declare function getNativeClientVersion(): {
+    schemaVersion: 1;
+    product: "native-marketing";
+    version: string;
+    packages: {
+        sdk: "@native-marketing/sdk";
+        cli: "@native-marketing/cli";
+    };
+    contractVersion: number;
+    minimumClientVersion: string;
+    apiMajor: number;
+    nodeMajor: number;
+    changes: string[];
+};
+export declare function checkNativeHttpVersion(options?: ContentFactoryClientOptions & {
+    timeoutMs?: number;
+    requireCompatibility?: boolean;
+}): Promise<{
+    client: {
+        schemaVersion: 1;
+        product: "native-marketing";
+        version: string;
+        packages: {
+            sdk: "@native-marketing/sdk";
+            cli: "@native-marketing/cli";
+        };
+        contractVersion: number;
+        minimumClientVersion: string;
+        apiMajor: number;
+        nodeMajor: number;
+        changes: string[];
+    };
+    compatibility: import("../contracts/index.js").NativeCompatibility;
+}>;

package/types/http/client.d.ts

@@ -2,6 +2,7 @@ import type { paths } from './generated/schema.js';
 export interface ContentFactoryClientOptions {
     baseUrl?: string;
     fetch?: (input: Request) => Promise<Response>;
+    compatibility?: 'check' | 'require';
 }
 /** 共用认证HTTP入口，空写动作与生产代理保持一致的JSON传输合同。 */
 export declare function createContentFactoryClient(options?: ContentFactoryClientOptions): import("openapi-fetch").Client<paths, `${string}/${string}`>;

package/types/http/index.d.ts

@@ -1,4 +1,6 @@
 export { createContentFactoryClient } from './client.js';
+export { getNativeClientVersion, checkNativeHttpVersion } from './client-version.js';
+export { assessNativeCompatibility, planNativeUpdate, defaultUpdatePolicy, type NativeClientRelease, type NativeClientIdentity, type NativeRegistryRelease, type NativeCompatibility, type NativeUpdatePolicy, type NativeUpdatePlan, } from '../contracts/index.js';
 export { readingDocument } from '../contracts/index.js';
 export { programActivationRequirements } from '../contracts/index.js';
 export type { ProjectAccessView, ProjectAccessChange } from '../contracts/index.js';

package/types/sdk/capability-definition.d.ts

@@ -3,6 +3,7 @@ export declare function verifyCapabilityDefinition(raw: unknown, name: string, e
 /** Per connection metadata only. A cache hit is never permission to execute. */
 export declare class CapabilityDefinitionCache {
     private readonly values;
+    clear(): void;
     remember(value: CapabilityDefinition): void;
     get(name: string, hash: string): {
         schemaVersion: 1;

package/types/sdk/cli/run.d.ts

@@ -2,6 +2,7 @@
 export declare function runNetworkCli(args: string[], env?: NodeJS.ProcessEnv, io?: {
     stdin?: AsyncIterable<string | Uint8Array>;
     notify?: (message: string) => void;
+    executablePath?: string;
 }, executable?: 'cf' | 'cf-agent'): Promise<{
     exitCode: number;
     envelope: {

package/types/sdk/client.d.ts

@@ -4,7 +4,10 @@ import { uploadNativeProjectMedia, uploadNativeMaterial, type NativeMaterialUplo
 import type { BusinessDocumentInput, AgentSummaryInput, AgentSummary, CapabilityCall, BusinessSearchQuery, BusinessSearchPage, BusinessContentPageRead, BusinessContentPage, CapabilityQuery, CapabilityPage, AgentCapabilityPage, CapabilityDefinition, CapabilitySchemaRead, BusinessDocumentPage } from '../contracts/index.js';
 import { readNativeCapabilityDescriptor, readNativeCapabilitySchemaPage } from './schema-pages.js';
 import { inspectNativeTool, listNativeToolsPage, type NativeToolOptions, type NativeToolResult } from './operations.js';
+import { readNativeServerVersion } from './updates/version.js';
 export interface NativeAgentClient {
+    getVersion(): ReturnType<typeof readNativeServerVersion>;
+    refreshVersion(): Promise<ReturnType<typeof readNativeServerVersion>>;
     readPackageFile(input: Parameters<typeof readNativePackageFile>[1]): ReturnType<typeof readNativePackageFile>;
     readProjectMediaFile(input: Parameters<typeof readNativeProjectMediaFile>[1]): ReturnType<typeof readNativeProjectMediaFile>;
     uploadProjectMedia(file: Parameters<typeof uploadNativeProjectMedia>[1]): ReturnType<typeof uploadNativeProjectMedia>;
@@ -32,4 +35,6 @@ export declare function withNativeAgentClient<T>(connection: {
     accessToken: string;
 }, action: (client: NativeAgentClient) => Promise<T>, options?: {
     timeoutMs?: number;
+    requireCompatibility?: boolean;
+    onVersion?: (version: ReturnType<typeof readNativeServerVersion>) => void;
 }): Promise<T>;

package/types/sdk/index.d.ts

@@ -17,3 +17,6 @@ export type { CapabilitySchemaRead, CapabilitySchemaPage } from '../contracts/in
 export { uploadNativeProjectMedia, uploadNativeMaterial, type NativeMaterialUpload, } from './material-upload.js';
 export { readNativeProjectMediaFile, projectMediaFileQuerySchema } from './project-media.js';
 export { readNativePackageFile } from './package-files.js';
+export { getNativeClientVersion } from './updates/version.js';
+export { checkNativeUpdates } from './updates/registry.js';
+export { assessNativeCompatibility, planNativeUpdate, defaultUpdatePolicy, type NativeClientRelease, type NativeClientIdentity, type NativeRegistryRelease, type NativeCompatibility, type NativeUpdatePolicy, type NativeUpdatePlan, } from '../contracts/index.js';

package/types/sdk/transport.d.ts

@@ -1,5 +1,10 @@
 import { Client, type Tool } from '@modelcontextprotocol/client';
 import { type Profile } from './profile.js';
+import { readNativeServerVersion } from './updates/version.js';
 /** 只访问远端正式工具；无本地数据库 fallback，也不重试未知结果的写操作。 */
-export declare function withClient<T>(profile: Profile, timeout: number, operation: (client: Client) => Promise<T>): Promise<T>;
+export declare function withClient<T>(profile: Profile, timeout: number, operation: (client: Client) => Promise<T>, options?: {
+    requireCompatibility?: boolean;
+    allowIncompatible?: boolean;
+    onVersion?: (version: ReturnType<typeof readNativeServerVersion>) => void;
+}): Promise<T>;
 export declare function callTool(client: Client, tool: Tool, input: Record<string, unknown>, timeout: number, readOnly: boolean, errorToolName?: string): Promise<unknown>;

package/types/sdk/updates/commands.d.ts

@@ -0,0 +1,11 @@
+import type { ParsedArgs } from '../cli/input.js';
+type Output = {
+    command: string;
+    data: unknown;
+};
+export declare function runLifecycleCommand(parsed: ParsedArgs, env: NodeJS.ProcessEnv, executablePath?: string): Promise<Output | null>;
+export declare function maybeAutoUpdate(env: NodeJS.ProcessEnv, io: {
+    executablePath?: string;
+    notify?: (message: string) => void;
+}, timeout: number): Promise<Output | null>;
+export {};

package/types/sdk/updates/install.d.ts

@@ -0,0 +1,20 @@
+import { type NativeRegistryRelease, type NativeUpdatePolicy } from '../../contracts/index.js';
+/** The only subprocess adapter in the client: fixed npm installation and version verification. */
+export declare function installCliUpdate(input: {
+    target: NativeRegistryRelease;
+    currentVersion?: string;
+    policy: NativeUpdatePolicy;
+    executablePath?: string;
+    allowBreaking?: boolean;
+    automatic?: boolean;
+    timeoutMs: number;
+    env: NodeJS.ProcessEnv;
+}): Promise<{
+    state: string;
+    package: "@native-marketing/cli" | "@native-marketing/sdk";
+    previousVersion: string;
+    installedVersion: string;
+    restartRequired: boolean;
+    originalCommandExecuted: boolean;
+    recovery: string[];
+}>;

package/types/sdk/updates/registry.d.ts

@@ -0,0 +1,26 @@
+import { type NativeClientRelease, type NativeUpdatePolicy } from '../../contracts/index.js';
+export declare function checkNativeUpdates(options?: {
+    package?: 'sdk' | 'cli';
+    currentVersion?: string;
+    policy?: NativeUpdatePolicy;
+    server?: NativeClientRelease;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}): Promise<{
+    checkedAt: number;
+    target: {
+        name: "@native-marketing/cli" | "@native-marketing/sdk";
+        version: string;
+        deprecated?: string | undefined;
+        nativeMarketing?: {
+            contractVersion: number;
+            apiMajor: number;
+            nodeMajor: number;
+            changes?: string[] | undefined;
+        } | undefined;
+        dist: {
+            integrity: string;
+        };
+    };
+    plan: import("../../contracts/index.js").NativeUpdatePlan;
+}>;

package/types/sdk/updates/store.d.ts

@@ -0,0 +1,14 @@
+import { type NativeClientUpdateState as State, type NativeUpdatePolicy } from '../../contracts/index.js';
+export declare class UpdateStore {
+    private readonly files;
+    constructor(env: NodeJS.ProcessEnv);
+    read(): Promise<State>;
+    locked<T>(action: () => Promise<T>): Promise<T>;
+    change(action: (state: State) => State): Promise<State>;
+}
+export declare function effectiveUpdatePolicy(policy: NativeUpdatePolicy, env: NodeJS.ProcessEnv): {
+    mode: "auto" | "notify" | "off";
+    channel: "beta" | "latest" | "next";
+    pin: string | null;
+    intervalHours: number;
+};

package/types/sdk/updates/version.d.ts

@@ -0,0 +1,93 @@
+import type { Client } from '@modelcontextprotocol/client';
+export declare function getNativeClientVersion(): {
+    schemaVersion: 1;
+    product: "native-marketing";
+    version: string;
+    packages: {
+        sdk: "@native-marketing/sdk";
+        cli: "@native-marketing/cli";
+    };
+    contractVersion: number;
+    minimumClientVersion: string;
+    apiMajor: number;
+    nodeMajor: number;
+    changes: string[];
+};
+export declare function getNativeCliVersion(executablePath?: string): Promise<{
+    schemaVersion: 1;
+    product: "native-marketing";
+    version: string;
+    packages: {
+        sdk: "@native-marketing/sdk";
+        cli: "@native-marketing/cli";
+    };
+    contractVersion: number;
+    minimumClientVersion: string;
+    apiMajor: number;
+    nodeMajor: number;
+    changes: string[];
+    sdkVersion: "0.3.7";
+}>;
+export declare function readNativeServerVersion(client: Client): {
+    client: {
+        schemaVersion: 1;
+        product: "native-marketing";
+        version: string;
+        packages: {
+            sdk: "@native-marketing/sdk";
+            cli: "@native-marketing/cli";
+        };
+        contractVersion: number;
+        minimumClientVersion: string;
+        apiMajor: number;
+        nodeMajor: number;
+        changes: string[];
+    };
+    serverInfo: {
+        version: string;
+        websiteUrl?: string | undefined;
+        description?: string | undefined;
+        icons?: {
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+            theme?: "dark" | "light" | undefined;
+        }[] | undefined;
+        name: string;
+        title?: string | undefined;
+    } | null;
+    mcpProtocolVersion: string | null;
+    compatibility: import("../../contracts/index.js").NativeCompatibility;
+};
+export declare function assertNativeCompatibility(result: ReturnType<typeof readNativeServerVersion>, required?: boolean): void;
+export declare function refreshNativeServerVersion(client: Client, timeout: number): Promise<{
+    client: {
+        schemaVersion: 1;
+        product: "native-marketing";
+        version: string;
+        packages: {
+            sdk: "@native-marketing/sdk";
+            cli: "@native-marketing/cli";
+        };
+        contractVersion: number;
+        minimumClientVersion: string;
+        apiMajor: number;
+        nodeMajor: number;
+        changes: string[];
+    };
+    serverInfo: {
+        version: string;
+        websiteUrl?: string | undefined;
+        description?: string | undefined;
+        icons?: {
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+            theme?: "dark" | "light" | undefined;
+        }[] | undefined;
+        name: string;
+        title?: string | undefined;
+    } | null;
+    mcpProtocolVersion: string | null;
+    compatibility: import("../../contracts/index.js").NativeCompatibility;
+}>;