@native-marketing/sdk 0.3.6 → 0.3.8

package/types/http/human-presentation.d.ts

@@ -0,0 +1,247 @@
+import { humanPresentationInputSchema, issueHumanReadLinkInputSchema, humanReadLinkLookupSchema, humanReadLinkReceiptQuerySchema, revokeHumanReadLinkInputSchema, cleanupHumanReadLinksInputSchema } from '../contracts/index.js';
+import type { z } from 'zod';
+import type { ContentFactoryClientOptions } from './client.js';
+import { ApiClientError } from './errors.js';
+export declare class HumanPresentationHttpError extends ApiClientError {
+    readonly outcome: 'NOT_SENT' | 'UNKNOWN' | 'REJECTED';
+    readonly details: Record<string, unknown>;
+    constructor(status: number, code: string, outcome: 'NOT_SENT' | 'UNKNOWN' | 'REJECTED', details: Record<string, unknown>);
+}
+export declare function createHumanPresentationHttpClient(options: ContentFactoryClientOptions & {
+    projectCode: string;
+    timeoutMs?: number;
+}): {
+    getHumanPresentation: (input: z.input<typeof humanPresentationInputSchema>) => Promise<{
+        human: {
+            schemaVersion: 1;
+            interactions: {
+                interactionRef: string;
+                kind: "CONTENT_PACKAGE_REVIEW";
+                subjectRef: string;
+                title: string;
+                summary: string;
+                state: "APPROVED" | "PENDING" | "REJECTED" | "RESOLVED";
+                sourceState: string;
+                actionDigest: string;
+                expiresAt: null;
+                reviewUrl: string;
+                canReview: boolean;
+            }[];
+            links: ({
+                linkRef: string;
+                kind: "READABLE_CONTENT";
+                title: string;
+                subjectRef: string;
+                url: string;
+                access: "AUTHENTICATED";
+                representation: "CURRENT_VIEW";
+                expiresAt: null;
+            } | {
+                linkRef: string;
+                kind: "READABLE_CONTENT";
+                title: string;
+                subjectRef: string;
+                url: string;
+                access: "TEMPORARY_PUBLIC_READ";
+                representation: "SNAPSHOT";
+                snapshotRef: string;
+                contentSha256: string;
+                createdAt: string;
+                expiresAt: string;
+            })[];
+        };
+    }>;
+    issueHumanReadLink: (input: z.input<typeof issueHumanReadLinkInputSchema>) => Promise<{
+        linkRef: string;
+        issuanceRequestId: string;
+        state: "ACTIVE" | "EXPIRED" | "REVOKED" | "UNAVAILABLE";
+        packageCode: string;
+        manifestHash: string;
+        expiresAt: string;
+        human: {
+            schemaVersion: 1;
+            interactions: {
+                interactionRef: string;
+                kind: "CONTENT_PACKAGE_REVIEW";
+                subjectRef: string;
+                title: string;
+                summary: string;
+                state: "APPROVED" | "PENDING" | "REJECTED" | "RESOLVED";
+                sourceState: string;
+                actionDigest: string;
+                expiresAt: null;
+                reviewUrl: string;
+                canReview: boolean;
+            }[];
+            links: ({
+                linkRef: string;
+                kind: "READABLE_CONTENT";
+                title: string;
+                subjectRef: string;
+                url: string;
+                access: "AUTHENTICATED";
+                representation: "CURRENT_VIEW";
+                expiresAt: null;
+            } | {
+                linkRef: string;
+                kind: "READABLE_CONTENT";
+                title: string;
+                subjectRef: string;
+                url: string;
+                access: "TEMPORARY_PUBLIC_READ";
+                representation: "SNAPSHOT";
+                snapshotRef: string;
+                contentSha256: string;
+                createdAt: string;
+                expiresAt: string;
+            })[];
+        };
+    }>;
+    getHumanReadLink: (input: z.input<typeof humanReadLinkLookupSchema>) => Promise<{
+        linkRef: string;
+        issuanceRequestId: string;
+        state: "ACTIVE" | "EXPIRED" | "REVOKED" | "UNAVAILABLE";
+        packageCode: string;
+        manifestHash: string;
+        expiresAt: string;
+        human: {
+            schemaVersion: 1;
+            interactions: {
+                interactionRef: string;
+                kind: "CONTENT_PACKAGE_REVIEW";
+                subjectRef: string;
+                title: string;
+                summary: string;
+                state: "APPROVED" | "PENDING" | "REJECTED" | "RESOLVED";
+                sourceState: string;
+                actionDigest: string;
+                expiresAt: null;
+                reviewUrl: string;
+                canReview: boolean;
+            }[];
+            links: ({
+                linkRef: string;
+                kind: "READABLE_CONTENT";
+                title: string;
+                subjectRef: string;
+                url: string;
+                access: "AUTHENTICATED";
+                representation: "CURRENT_VIEW";
+                expiresAt: null;
+            } | {
+                linkRef: string;
+                kind: "READABLE_CONTENT";
+                title: string;
+                subjectRef: string;
+                url: string;
+                access: "TEMPORARY_PUBLIC_READ";
+                representation: "SNAPSHOT";
+                snapshotRef: string;
+                contentSha256: string;
+                createdAt: string;
+                expiresAt: string;
+            })[];
+        };
+    }>;
+    getHumanReadLinkReceipt: (input: z.input<typeof humanReadLinkReceiptQuerySchema>) => Promise<{
+        status: "FOUND";
+        receipt: {
+            linkRef: string;
+            issuanceRequestId: string;
+            state: "ACTIVE" | "EXPIRED" | "REVOKED" | "UNAVAILABLE";
+            packageCode: string;
+            manifestHash: string;
+            expiresAt: string;
+            human: {
+                schemaVersion: 1;
+                interactions: {
+                    interactionRef: string;
+                    kind: "CONTENT_PACKAGE_REVIEW";
+                    subjectRef: string;
+                    title: string;
+                    summary: string;
+                    state: "APPROVED" | "PENDING" | "REJECTED" | "RESOLVED";
+                    sourceState: string;
+                    actionDigest: string;
+                    expiresAt: null;
+                    reviewUrl: string;
+                    canReview: boolean;
+                }[];
+                links: ({
+                    linkRef: string;
+                    kind: "READABLE_CONTENT";
+                    title: string;
+                    subjectRef: string;
+                    url: string;
+                    access: "AUTHENTICATED";
+                    representation: "CURRENT_VIEW";
+                    expiresAt: null;
+                } | {
+                    linkRef: string;
+                    kind: "READABLE_CONTENT";
+                    title: string;
+                    subjectRef: string;
+                    url: string;
+                    access: "TEMPORARY_PUBLIC_READ";
+                    representation: "SNAPSHOT";
+                    snapshotRef: string;
+                    contentSha256: string;
+                    createdAt: string;
+                    expiresAt: string;
+                })[];
+            };
+        };
+    } | {
+        status: "NOT_FOUND";
+    }>;
+    revokeHumanReadLink: (input: z.input<typeof revokeHumanReadLinkInputSchema>) => Promise<{
+        linkRef: string;
+        issuanceRequestId: string;
+        state: "ACTIVE" | "EXPIRED" | "REVOKED" | "UNAVAILABLE";
+        packageCode: string;
+        manifestHash: string;
+        expiresAt: string;
+        human: {
+            schemaVersion: 1;
+            interactions: {
+                interactionRef: string;
+                kind: "CONTENT_PACKAGE_REVIEW";
+                subjectRef: string;
+                title: string;
+                summary: string;
+                state: "APPROVED" | "PENDING" | "REJECTED" | "RESOLVED";
+                sourceState: string;
+                actionDigest: string;
+                expiresAt: null;
+                reviewUrl: string;
+                canReview: boolean;
+            }[];
+            links: ({
+                linkRef: string;
+                kind: "READABLE_CONTENT";
+                title: string;
+                subjectRef: string;
+                url: string;
+                access: "AUTHENTICATED";
+                representation: "CURRENT_VIEW";
+                expiresAt: null;
+            } | {
+                linkRef: string;
+                kind: "READABLE_CONTENT";
+                title: string;
+                subjectRef: string;
+                url: string;
+                access: "TEMPORARY_PUBLIC_READ";
+                representation: "SNAPSHOT";
+                snapshotRef: string;
+                contentSha256: string;
+                createdAt: string;
+                expiresAt: string;
+            })[];
+        };
+    }>;
+    cleanupHumanReadLinks: (input?: z.input<typeof cleanupHumanReadLinksInputSchema>) => Promise<{
+        reclaimed: number;
+        limit: number;
+    }>;
+};

package/types/http/index.d.ts

@@ -1,4 +1,8 @@
 export { createContentFactoryClient } from './client.js';
+export { createHumanPresentationHttpClient, HumanPresentationHttpError, } from './human-presentation.js';
+export type { HumanPresentation, HumanInteraction, HumanReadLink, HumanReadLinkResult, IssueHumanReadLinkInput, } from '../contracts/index.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/commands.d.ts

@@ -2,7 +2,7 @@ import type { Client } from '@modelcontextprotocol/client';
 import type { ParsedArgs } from './input.js';
 export declare function resolveCommand(parsed: ParsedArgs): {
     tool?: string;
-    mode: 'media-file' | 'package-file' | 'upload' | 'list' | 'inspect' | 'call' | 'discover' | 'describe' | 'search' | 'business-read' | 'summary' | 'capability-call' | 'capability-read' | 'capability-write' | 'document' | 'schema' | 'descriptor';
+    mode: 'media-file' | 'package-file' | 'upload' | 'list' | 'inspect' | 'call' | 'discover' | 'describe' | 'search' | 'business-read' | 'summary' | 'capability-call' | 'capability-read' | 'capability-write' | 'document' | 'schema' | 'descriptor' | 'human';
 };
 /** 工具目录由当前服务器提供；有分页时有界查找，不以本地名称推断授权。 */
 export declare function businessCommand(client: Client, parsed: ParsedArgs, input: Record<string, unknown>, resource: string): Promise<unknown>;

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

@@ -0,0 +1,8 @@
+export declare function formatNetworkCliResult(result: {
+    envelope: {
+        ok: boolean;
+        command: string;
+        data: unknown;
+        error: unknown;
+    };
+}, json?: boolean): string;

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

@@ -2,9 +2,19 @@ import { readNativePackageFile } from './package-files.js';
 import { readNativeProjectMediaFile } from './project-media.js';
 import { uploadNativeProjectMedia, uploadNativeMaterial, type NativeMaterialUpload } from './material-upload.js';
 import type { BusinessDocumentInput, AgentSummaryInput, AgentSummary, CapabilityCall, BusinessSearchQuery, BusinessSearchPage, BusinessContentPageRead, BusinessContentPage, CapabilityQuery, CapabilityPage, AgentCapabilityPage, CapabilityDefinition, CapabilitySchemaRead, BusinessDocumentPage } from '../contracts/index.js';
+import { getNativeHumanPresentation, issueNativeHumanReadLink, getNativeHumanReadLink, getNativeHumanReadLinkReceipt, revokeNativeHumanReadLink, cleanupNativeHumanReadLinks } from './human-presentation.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 {
+    getHumanPresentation(input: Parameters<typeof getNativeHumanPresentation>[2]): ReturnType<typeof getNativeHumanPresentation>;
+    issueHumanReadLink(input: Parameters<typeof issueNativeHumanReadLink>[2]): ReturnType<typeof issueNativeHumanReadLink>;
+    getHumanReadLink(input: Parameters<typeof getNativeHumanReadLink>[2]): ReturnType<typeof getNativeHumanReadLink>;
+    getHumanReadLinkReceipt(input: Parameters<typeof getNativeHumanReadLinkReceipt>[2]): ReturnType<typeof getNativeHumanReadLinkReceipt>;
+    revokeHumanReadLink(input: Parameters<typeof revokeNativeHumanReadLink>[2]): ReturnType<typeof revokeNativeHumanReadLink>;
+    cleanupHumanReadLinks(input?: Parameters<typeof cleanupNativeHumanReadLinks>[2]): ReturnType<typeof cleanupNativeHumanReadLinks>;
+    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 +42,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>;