@native-marketing/sdk 0.3.5 → 0.3.7

package/package.json

@@ -1,11 +1,21 @@
 {
   "name": "@native-marketing/sdk",
-  "version": "0.3.5",
+  "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": "667f36fbe201292e233c4be3cc8ba84483867fd9",
+  "sourceCommit": "170f43ed793abd2cee15faaba49428aa43c276cd",
   "workingTreeDirty": false,
-  "version": "0.3.5",
-  "openapiTypesSha256": "4cf54da717c27d1df685ee4756f78c5094e90fe72c3d3047e7b901b7e8b6c1b8",
+  "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/human-knowledge.d.ts

@@ -507,6 +507,8 @@ export declare const humanKnowledgeItemDetailSchema: z.ZodObject<{
     contentAvailable: z.ZodBoolean;
     projectBound: z.ZodNullable<z.ZodBoolean>;
     selected: z.ZodBoolean;
+    referenceRepairRequired: z.ZodOptional<z.ZodBoolean>;
+    resourceLinked: z.ZodOptional<z.ZodBoolean>;
     originalUrl: z.ZodNullable<z.ZodString>;
     evidenceRefs: z.ZodArray<z.ZodString>;
     relatedRefs: z.ZodArray<z.ZodString>;

package/types/contracts/index.d.ts

@@ -107,6 +107,7 @@ export * from './business-command-receipt.js';
 export * from './operating-command-receipts.js';
 export * from './feedback-facts.js';
 export * from './knowledge-discovery.js';
+export * from './knowledge-reference-repair.js';
 export * from './event-exchange.js';
 export * from './event-exchange-browser.js';
 export { EVENTSDK_WORKER_OBSERVATION_MAX_AGE_MS, eventDeliveryPageQuerySchema, eventDeliveryPageSchema, eventDeliveryRecoveryResultSchema, eventDeliveryRecoveryReceiptSchema, } from './event-delivery.js';
@@ -116,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/contracts/knowledge-discovery.d.ts

@@ -133,9 +133,9 @@ export declare const knowledgeDiscoveryDescriptionSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type KnowledgeDiscoveryDescription = z.infer<typeof knowledgeDiscoveryDescriptionSchema>;
 export declare const knowledgeAdoptionCommandSchema: z.ZodObject<{
-    ref: z.ZodNonOptional<z.ZodString>;
     expectedContentHash: z.ZodNonOptional<z.ZodOptional<z.ZodString>>;
     requestId: z.ZodString;
+    ref: z.ZodString;
 }, z.core.$strict>;
 export declare const knowledgeAdoptionResultSchema: z.ZodObject<{
     result: z.ZodObject<{
@@ -213,3 +213,13 @@ export declare const adoptedKnowledgeResourceSchema: z.ZodObject<{
     identityHash: z.ZodString;
 }, z.core.$strict>;
 export type KnowledgeAdoptionCommand = z.infer<typeof knowledgeAdoptionCommandSchema>;
+export declare const knowledgeResourceDescriptorSchema: z.ZodObject<{
+    ref: z.ZodString;
+    ownerTenantId: z.ZodString;
+    resourceType: z.ZodString;
+    identityHash: z.ZodString;
+    kind: z.ZodString;
+    classification: z.ZodString;
+    title: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+}, z.core.$strict>;

package/types/contracts/knowledge-reference-repair.d.ts

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+export declare const knowledgeReferenceRepairQuerySchema: z.ZodObject<{
+    sourceRef: z.ZodString;
+}, z.core.$strict>;
+export declare const knowledgeReferenceRepairPreviewSchema: z.ZodObject<{
+    sourceRef: z.ZodString;
+    remoteRef: z.ZodString;
+    basisHash: z.ZodString;
+    sourceTenantId: z.ZodString;
+    item: z.ZodObject<{
+        ref: z.ZodString;
+        ownerTenantId: z.ZodString;
+        resourceType: z.ZodString;
+        originType: z.ZodEnum<{
+            LEGACY_PROJECT: "LEGACY_PROJECT";
+            TENANT_AUTHOR: "TENANT_AUTHOR";
+            TENANT_SOURCE: "TENANT_SOURCE";
+        }>;
+        identityHash: z.ZodString;
+        identityKind: z.ZodEnum<{
+            CAS_BYTES: "CAS_BYTES";
+            REFERENCE_RECORD_DIGEST: "REFERENCE_RECORD_DIGEST";
+        }>;
+        kind: z.ZodString;
+        classification: z.ZodString;
+        mediaType: z.ZodString;
+        title: z.ZodString;
+        summary: z.ZodString;
+        readable: z.ZodBoolean;
+        reasonCodes: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    byteLength: z.ZodNumber;
+    verified: z.ZodLiteral<true>;
+}, z.core.$strict>;
+export declare const knowledgeReferenceRepairCommandSchema: z.ZodObject<{
+    sourceRef: z.ZodString;
+    requestId: z.ZodString;
+    expectedBasisHash: z.ZodString;
+}, z.core.$strict>;
+export declare const knowledgeReferenceRepairResultSchema: z.ZodObject<{
+    result: z.ZodObject<{
+        id: z.ZodString;
+        ref: z.ZodString;
+        tenantId: z.ZodString;
+        sourceType: z.ZodEnum<{
+            CASE_EVIDENCE: "CASE_EVIDENCE";
+            EXTERNAL_REFERENCE: "EXTERNAL_REFERENCE";
+            HOT_TOPIC: "HOT_TOPIC";
+            HUMAN_IDEA: "HUMAN_IDEA";
+            INSIGHT: "INSIGHT";
+            KNOWLEDGE: "KNOWLEDGE";
+            NEWS: "NEWS";
+            TREND: "TREND";
+            WORLD_FACT: "WORLD_FACT";
+        }>;
+        sourceRef: z.ZodString;
+        sourceAuthority: z.ZodString;
+        observedAt: z.ZodNullable<z.ZodString>;
+        validUntil: z.ZodNullable<z.ZodString>;
+        evidenceRef: z.ZodNullable<z.ZodString>;
+        snapshotHash: z.ZodNullable<z.ZodString>;
+        metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>;
+    replayed: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const knowledgeReferenceRepairReceiptQuerySchema: z.ZodObject<{
+    requestId: z.ZodString;
+}, z.core.$strict>;
+export declare const knowledgeReferenceRepairReceiptSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"FOUND">;
+    result: z.ZodObject<{
+        id: z.ZodString;
+        ref: z.ZodString;
+        tenantId: z.ZodString;
+        sourceType: z.ZodEnum<{
+            CASE_EVIDENCE: "CASE_EVIDENCE";
+            EXTERNAL_REFERENCE: "EXTERNAL_REFERENCE";
+            HOT_TOPIC: "HOT_TOPIC";
+            HUMAN_IDEA: "HUMAN_IDEA";
+            INSIGHT: "INSIGHT";
+            KNOWLEDGE: "KNOWLEDGE";
+            NEWS: "NEWS";
+            TREND: "TREND";
+            WORLD_FACT: "WORLD_FACT";
+        }>;
+        sourceRef: z.ZodString;
+        sourceAuthority: z.ZodString;
+        observedAt: z.ZodNullable<z.ZodString>;
+        validUntil: z.ZodNullable<z.ZodString>;
+        evidenceRef: z.ZodNullable<z.ZodString>;
+        snapshotHash: z.ZodNullable<z.ZodString>;
+        metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"NOT_FOUND">;
+    result: z.ZodNull;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"REJECTED">;
+    result: z.ZodNull;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        outcome: z.ZodLiteral<"REJECTED">;
+        recovery: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>], "state">;
+export type KnowledgeReferenceRepairPreview = z.infer<typeof knowledgeReferenceRepairPreviewSchema>;

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}`>;