@peers-app/peers-sdk 0.23.4 → 0.23.6

package/dist/package-loader/isolated-artifact.d.ts

@@ -0,0 +1,233 @@
+import type { IAlsoImplementsDeclaration, IConsumedContract, IContractDefinition, IContractObservable, IContractTool } from "../contracts/types";
+import { type PersistentVarScope } from "../data/persistent-var-identity";
+import type { IAppNav } from "../types/app-nav";
+import { type IField } from "../types/field-type";
+/**
+ * First line of an isolated package bundle. Existing `package.bundle.js`
+ * artifacts never start with this token, so the loader can detect the
+ * opt-in format without evaluating source.
+ */
+export declare const ISOLATED_PACKAGE_MAGIC = "PEERS_ISOLATED_PACKAGE_V1";
+/**
+ * Stable tool identity for isolated (and future contract-first) tools:
+ * `contractId + version + toolName`.
+ */
+export interface IIsolatedContractToolRef {
+    contractId: string;
+    version: number;
+    toolName: string;
+}
+/**
+ * Tool advertised on an isolated provided contract.
+ *
+ * Shape matches {@link IContractTool}. `suggestedAccessLevel` is a package
+ * hint only — the host keeps the effective level at Self until an
+ * administrator approves it.
+ */
+export interface IIsolatedContractTool extends Omit<IContractTool, "inputFields" | "outputFields"> {
+    /** Defaults to `[]` during validation when omitted. */
+    inputFields?: IField[];
+    /** Defaults to `[]` during validation when omitted. */
+    outputFields?: IField[];
+    /** Package suggestion only. Effective level stays Self until approved. */
+    suggestedAccessLevel?: number;
+}
+/**
+ * Private table schema declared by an isolated package.
+ *
+ * The host derives package-scoped physical identity. Contract consumers never
+ * receive this schema or raw table access.
+ */
+export interface IIsolatedPackageTable {
+    name: string;
+    description?: string;
+    primaryKeyName: string;
+    fields: IField[];
+    /** Schema version for host table-definition updates. Defaults to `1`. */
+    versionNumber?: number;
+}
+/** Name-only reference that exposes one package table through a contract. */
+export interface IIsolatedContractTableRef {
+    name: string;
+}
+/** Trusted manifest binding from a contract observable to a package-owned pvar. */
+export interface IIsolatedContractPersistentVarBinding {
+    scope: PersistentVarScope;
+    name: string;
+    defaultValue: unknown;
+}
+/** Observable contract member backed by a package-owned persistent variable. */
+export interface IIsolatedContractObservable extends IContractObservable {
+    persistentVar: IIsolatedContractPersistentVarBinding;
+}
+/** Contract this package implements and serves from its isolated worker. */
+export interface IIsolatedProvidedContract {
+    contractId: string;
+    version: number;
+    name: string;
+    description?: string;
+    tools: IIsolatedContractTool[];
+    /** Name-only references to package tables exposed to consumers. */
+    tables?: IIsolatedContractTableRef[];
+    /** Pvar-backed observable values exposed to consumers. */
+    observables?: IIsolatedContractObservable[];
+    /** Older contract versions this provider shape also satisfies. */
+    alsoImplements?: IAlsoImplementsDeclaration[];
+}
+/** Contract this package is allowed to call through the trusted host. */
+export interface IIsolatedConsumedContract {
+    contractId: string;
+    version: number;
+    optional?: boolean;
+    providerPackageIds?: string[];
+    fallbackToDefaultProvider?: boolean;
+}
+/**
+ * Pure-data package description. Validated on the host; never executed there.
+ */
+export interface IIsolatedPackageManifest {
+    packageId: string;
+    version: string;
+    provides: IIsolatedProvidedContract[];
+    consumes: IIsolatedConsumedContract[];
+    /** Package-owned table schemas. Contract references decide public exposure. */
+    tables?: IIsolatedPackageTable[];
+    appNavs?: IAppNav[];
+}
+/**
+ * Installable isolated package: declarative manifest plus provider source
+ * that may run only inside a supervised worker.
+ */
+export interface IIsolatedPackageArtifact {
+    manifest: IIsolatedPackageManifest;
+    providerSource: string;
+}
+/** Outcome of installing one isolated artifact into a host runtime. */
+export interface IIsolatedInstallResult {
+    packageId: string;
+    provided: Array<{
+        contractId: string;
+        version: number;
+    }>;
+    consumes: Array<{
+        contractId: string;
+        version: number;
+        optional?: boolean;
+        satisfied: boolean;
+    }>;
+}
+/** Snapshot of an installed isolated package (no provider source). */
+export interface IIsolatedInstalledPackage {
+    packageId: string;
+    version: string;
+    provides: IIsolatedProvidedContract[];
+    consumes: IIsolatedConsumedContract[];
+    tables: IIsolatedPackageTable[];
+    definitions: IContractDefinition[];
+    appNavs?: IAppNav[];
+}
+/** Host-contract member guests use to request a consumed-contract tool call. */
+export declare const ISOLATED_CONSUME_HOST_MEMBER = "contract.consume";
+/** Host-contract member guests use to read or write a package-owned table. */
+export declare const ISOLATED_TABLE_HOST_MEMBER = "package.table";
+/** Host-contract member guests use to read or write package-prefixed pvars. */
+export declare const ISOLATED_PERSISTENT_VAR_HOST_MEMBER = "package.pvar";
+/**
+ * True when `bundle` starts with {@link ISOLATED_PACKAGE_MAGIC}.
+ *
+ * A recognized header must never fall through to `new Function` evaluation,
+ * even if the rest of the envelope is malformed.
+ *
+ * @param bundle - Package bundle text from Files or `dist/package.bundle.js`.
+ */
+export declare function looksLikeIsolatedPackageArtifact(bundle: string): boolean;
+/**
+ * Validate a wire-safe isolated package artifact. Does not evaluate
+ * `providerSource`.
+ *
+ * @param artifact - Parsed artifact object.
+ * @returns The same manifest after in-place field normalization.
+ * @throws If identity, contracts, tools, or source are invalid.
+ */
+export declare function validateIsolatedPackageArtifact(artifact: IIsolatedPackageArtifact): IIsolatedPackageManifest;
+/**
+ * Parse a magic-header + JSON isolated package bundle.
+ *
+ * @param bundle - Full package-bundle text.
+ * @returns The validated artifact.
+ * @throws If the magic header is present but the envelope is malformed.
+ */
+export declare function parseIsolatedPackageArtifact(bundle: string): IIsolatedPackageArtifact;
+/**
+ * Serialize an isolated artifact into the package-bundle slot format.
+ *
+ * @param artifact - Validated or soon-to-be-validated artifact.
+ */
+export declare function serializeIsolatedPackageArtifact(artifact: IIsolatedPackageArtifact): string;
+/**
+ * Convert a provided-contract declaration into an SDK contract definition.
+ *
+ * Name-only table references are resolved from the package's schema list.
+ * Persistent-variable bindings stay host-only and are omitted from the public
+ * observable definition.
+ *
+ * @param contract - Isolated provided-contract declaration.
+ * @param packageTables - Package-owned schemas available for contract exposure.
+ */
+export declare function isolatedContractToDefinition(contract: IIsolatedProvidedContract, packageTables: IIsolatedPackageTable[]): IContractDefinition;
+/**
+ * True when `consumes` names this exact contract version.
+ *
+ * @param consumes - Declared package dependencies.
+ * @param contractId - Target contract id.
+ * @param version - Target contract version.
+ */
+export declare function packageDeclaresConsume(consumes: IIsolatedConsumedContract[], contractId: string, version: number): boolean;
+/**
+ * True when the package advertises this tool on a provided contract.
+ *
+ * @param provides - Provided contracts from the manifest.
+ * @param contractId - Target contract id.
+ * @param version - Target contract version.
+ * @param toolName - Tool name on that contract.
+ */
+export declare function packageProvidesTool(provides: IIsolatedProvidedContract[], contractId: string, version: number, toolName: string): boolean;
+/**
+ * Return a consumer-facing table reference from a provided contract.
+ *
+ * @param provides Provided contracts from the manifest.
+ * @param contractId Target contract ID.
+ * @param version Target contract version.
+ * @param tableName Public table name.
+ */
+export declare function findProvidedContractTable(provides: IIsolatedProvidedContract[], contractId: string, version: number, tableName: string): IIsolatedContractTableRef | undefined;
+/**
+ * Return a pvar-backed observable from a provided contract.
+ *
+ * @param provides Provided contracts from the manifest.
+ * @param contractId Target contract ID.
+ * @param version Target contract version.
+ * @param observableName Public observable name.
+ */
+export declare function findProvidedContractObservable(provides: IIsolatedProvidedContract[], contractId: string, version: number, observableName: string): IIsolatedContractObservable | undefined;
+/**
+ * True when the package declares a private table.
+ *
+ * @param tables - Package-private table schemas.
+ * @param tableName - Package-local table name.
+ */
+export declare function packageProvidesTable(tables: IIsolatedPackageTable[], tableName: string): boolean;
+/**
+ * Return the declared table when this package owns it.
+ *
+ * @param tables - Package-private table schemas.
+ * @param tableName - Package-local table name.
+ */
+export declare function findPackageTable(tables: IIsolatedPackageTable[], tableName: string): IIsolatedPackageTable | undefined;
+/**
+ * Map isolated consume declarations onto the registry's
+ * {@link IConsumedContract} shape (no deferred handles).
+ *
+ * @param consumes - Isolated consume list.
+ */
+export declare function toConsumedContracts(consumes: IIsolatedConsumedContract[]): IConsumedContract[];