@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/continuum/homeScenePackageCommand.d.ts

@@ -0,0 +1,44 @@
+import type { Command } from 'commander';
+import type { CliCredentials } from '../config';
+import { type HomeShellItem } from './homeScenePackage';
+type HomeShellAsset = {
+    rendition?: string | null;
+    cdnUrl?: string | null;
+    metadata?: {
+        bundle?: {
+            format?: string;
+            version?: number;
+            baseUrl?: string;
+        } | null;
+    } | null;
+};
+export interface HomeScenePackageDependencies {
+    requireAuth(): CliCredentials;
+    /** `GET /api/v1/universal-items/:id`, unwrapped to the item record. */
+    readUniversalItem(credentials: CliCredentials, itemId: string): Promise<HomeShellItem & {
+        assets?: HomeShellAsset[];
+    }>;
+    /** Fetch published bytes by absolute URL. */
+    readPublishedBytes(url: string): Promise<Uint8Array>;
+    /** Write a descriptor-relative file, creating parent directories. */
+    writeFile(directory: string, relativePath: string, bytes: Uint8Array): Promise<void>;
+    printJson(value: unknown): void;
+    fail(message: string): never;
+}
+/**
+ * `helix continuum home-scene-package <itemId> --out <dir>`
+ *
+ * Emit the Continuum publication descriptor for a Home Shell that is already
+ * published, together with the exact bytes it roots on, so that
+ * `helix continuum publish-package` can seal the Scene Package, create its
+ * public Vault and Marketplace Listings and pin it onto the Item — in one
+ * resumable, exact-ID publication.
+ *
+ * This is deliberately two commands rather than one. The descriptor is a plain
+ * file a creator can read, diff and keep as the record of what was published,
+ * and `publish-package` is the single audited door every other Package goes
+ * through. Nothing here is Home-specific except knowing where a Home Shell
+ * keeps its Scene document.
+ */
+export declare function registerContinuumHomeScenePackageCommand(continuum: Command, dependencies: HomeScenePackageDependencies): void;
+export {};

package/dist/continuum/homeScenePackageCommand.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerContinuumHomeScenePackageCommand = registerContinuumHomeScenePackageCommand;
+const homeScenePackage_1 = require("./homeScenePackage");
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+/**
+ * `helix continuum home-scene-package <itemId> --out <dir>`
+ *
+ * Emit the Continuum publication descriptor for a Home Shell that is already
+ * published, together with the exact bytes it roots on, so that
+ * `helix continuum publish-package` can seal the Scene Package, create its
+ * public Vault and Marketplace Listings and pin it onto the Item — in one
+ * resumable, exact-ID publication.
+ *
+ * This is deliberately two commands rather than one. The descriptor is a plain
+ * file a creator can read, diff and keep as the record of what was published,
+ * and `publish-package` is the single audited door every other Package goes
+ * through. Nothing here is Home-specific except knowing where a Home Shell
+ * keeps its Scene document.
+ */
+function registerContinuumHomeScenePackageCommand(continuum, dependencies) {
+    continuum
+        .command('home-scene-package')
+        .description('Derive the Scene Package publication descriptor for a published Home Shell (Vault + Marketplace + Item pin)')
+        .argument('<itemId>', 'the published Home Shell Universal Item')
+        .requiredOption('--out <dir>', 'directory to write the descriptor and its objects into')
+        .option('--package-version <semver>', 'Package Version to publish (default 1.0.0)')
+        .option('--slug <slug>', 'Package slug (default <item slug>-scene)')
+        .option('--package-id <uuid>', 'publish into an existing Package instead of the derived one')
+        .option('--tags <tags>', 'comma-separated Listing tags (default the Item tags)')
+        .option('--promote-to-published', 'publish the Universal Item alongside the pin')
+        .action(async (itemId, options) => {
+        try {
+            if (!UUID.test(itemId))
+                throw new TypeError('item id must be a UUID');
+            if (options.packageVersion && !SEMVER.test(options.packageVersion)) {
+                throw new TypeError('--package-version must be a semantic version');
+            }
+            if (options.packageId && !UUID.test(options.packageId)) {
+                throw new TypeError('--package-id must be a UUID');
+            }
+            const credentials = dependencies.requireAuth();
+            const item = await dependencies.readUniversalItem(credentials, itemId);
+            const asset = (item.assets ?? []).find((candidate) => (candidate.rendition ?? '').toLowerCase() === 'home-shell');
+            if (!asset) {
+                throw new TypeError(`Home Shell ${itemId} has no published home-shell asset`);
+            }
+            const bundleRoot = (0, homeScenePackage_1.homeShellSceneBundleRoot)(asset);
+            if (!bundleRoot) {
+                throw new TypeError(`Home Shell ${itemId} publishes no HELIX Scene v2 bundle; only a Scene-backed shell can become a Scene Package`);
+            }
+            const sceneBytes = await dependencies.readPublishedBytes(`${bundleRoot}/scene.helix-scene.json`);
+            const scene = JSON.parse(Buffer.from(sceneBytes).toString('utf8'));
+            const resources = [];
+            for (const resource of scene.resources ?? []) {
+                if (resource.source.kind !== 'bundle' || !resource.source.uri)
+                    continue;
+                resources.push({
+                    uri: resource.source.uri,
+                    bytes: await dependencies.readPublishedBytes(`${bundleRoot}/${resource.source.uri}`),
+                });
+            }
+            const derived = (0, homeScenePackage_1.deriveHomeScenePackage)({
+                item,
+                sceneBytes,
+                resources,
+                version: options.packageVersion,
+                packageSlug: options.slug,
+                packageId: options.packageId,
+                tags: options.tags
+                    ? options.tags.split(',').map((tag) => tag.trim()).filter(Boolean)
+                    : undefined,
+                promoteToPublished: options.promoteToPublished === true,
+            });
+            await dependencies.writeFile(options.out, 'scene.helix-scene.json', sceneBytes);
+            for (const resource of resources) {
+                await dependencies.writeFile(options.out, resource.uri, resource.bytes);
+            }
+            await dependencies.writeFile(options.out, 'continuum-publication.json', Buffer.from(`${JSON.stringify(derived.descriptor, null, 2)}\n`, 'utf8'));
+            dependencies.printJson({
+                contract: 'helix.creator.home-scene-package/1',
+                itemId,
+                itemSlug: item.slug,
+                packageId: derived.descriptor.package.id,
+                packageSlug: derived.descriptor.packagePublication.slug,
+                packageVersion: derived.descriptor.packageVersion.version,
+                sceneId: scene.id,
+                sceneRevision: scene.revision,
+                objectCount: derived.descriptor.packageVersion.expectedClosure.objectCount,
+                totalBytes: derived.descriptor.packageVersion.expectedClosure.totalBytes,
+                // A Home that declares only a `home` profile is discoverable and
+                // buyable but cannot be mounted into someone else's map, because a
+                // mount resolves against a `world`-kind profile. Say so here rather
+                // than letting the creator find out at mount time.
+                mountable: derived.mountable,
+                externalResources: derived.externalResources,
+                descriptor: 'continuum-publication.json',
+                next: `helix continuum publish-package ${options.out}/continuum-publication.json --confirm-public-listing`,
+            });
+        }
+        catch (error) {
+            dependencies.fail(`✖ ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
+//# sourceMappingURL=homeScenePackageCommand.js.map

package/dist/continuum/homeScenePackageCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"homeScenePackageCommand.js","sourceRoot":"","sources":["../../src/continuum/homeScenePackageCommand.ts"],"names":[],"mappings":"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"}

package/dist/continuum/identity.d.ts

@@ -0,0 +1,4 @@
+export declare const CONTINUUM_UUID_PATTERN: RegExp;
+export declare function assertContinuumUuid(value: string, label: string): void;
+/** Deterministic UUIDv5-shaped identity over a HELIX-owned namespace string. */
+export declare function deterministicContinuumUuid(namespace: string): string;

package/dist/continuum/identity.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTINUUM_UUID_PATTERN = void 0;
+exports.assertContinuumUuid = assertContinuumUuid;
+exports.deterministicContinuumUuid = deterministicContinuumUuid;
+const node_crypto_1 = require("node:crypto");
+exports.CONTINUUM_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function assertContinuumUuid(value, label) {
+    if (!exports.CONTINUUM_UUID_PATTERN.test(value))
+        throw new TypeError(`${label} must be a UUID`);
+}
+/** Deterministic UUIDv5-shaped identity over a HELIX-owned namespace string. */
+function deterministicContinuumUuid(namespace) {
+    const bytes = (0, node_crypto_1.createHash)('sha256').update(namespace).digest().subarray(0, 16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x50;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+//# sourceMappingURL=identity.js.map

package/dist/continuum/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/continuum/identity.ts"],"names":[],"mappings":";;;AAIA,kDAEC;AAGD,gEAMC;AAfD,6CAAyC;AAE5B,QAAA,sBAAsB,GAAG,4EAA4E,CAAC;AAEnH,SAAgB,mBAAmB,CAAC,KAAa,EAAE,KAAa;IAC9D,IAAI,CAAC,8BAAsB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,GAAG,KAAK,iBAAiB,CAAC,CAAC;AAC1F,CAAC;AAED,gFAAgF;AAChF,SAAgB,0BAA0B,CAAC,SAAiB;IAC1D,MAAM,KAAK,GAAG,IAAA,wBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACpC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACpC,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClC,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;AAC7G,CAAC"}

package/dist/continuum/index.d.ts

@@ -0,0 +1,11 @@
+export * from './authoring';
+export * from './characterMigrationGenerator';
+export * from './client';
+export * from './cli';
+export * from './homeScenePackage';
+export * from './identity';
+export * from './pull';
+export * from './sourceBundle';
+export * from './state';
+export * from './types';
+export * from './workflow';

package/dist/continuum/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./authoring"), exports);
+__exportStar(require("./characterMigrationGenerator"), exports);
+__exportStar(require("./client"), exports);
+__exportStar(require("./cli"), exports);
+__exportStar(require("./homeScenePackage"), exports);
+__exportStar(require("./identity"), exports);
+__exportStar(require("./pull"), exports);
+__exportStar(require("./sourceBundle"), exports);
+__exportStar(require("./state"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./workflow"), exports);
+//# sourceMappingURL=index.js.map

package/dist/continuum/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/continuum/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,gEAA8C;AAC9C,2CAAyB;AACzB,wCAAsB;AACtB,qDAAmC;AACnC,6CAA2B;AAC3B,yCAAuB;AACvB,iDAA+B;AAC/B,0CAAwB;AACxB,0CAAwB;AACxB,6CAA2B"}

package/dist/continuum/missingNormals.d.ts

@@ -0,0 +1,48 @@
+import type { ContinuumPackageVersion } from '@hypersoniclabs/helix-manifest';
+import { type EnsureNormalsReport } from '../glb/smooth-normals';
+import type { ContinuumObjectPublication } from './types';
+/**
+ * Publication-time guard for a Package's GLB objects.
+ *
+ * A GLB with no NORMAL attribute renders faceted everywhere (glTF 2.0 makes
+ * every runtime fall back to flat face normals), and a sealed Package Version
+ * is immutable: the bytes you seal are the bytes every owner gets, forever.
+ * The only moment the defect is cheap to fix is before sealing, so
+ * `helix continuum publish-package` writes smooth NORMALs into any GLB object
+ * that lacks them, then re-derives the CID and byte counts the descriptor
+ * declared.
+ *
+ * That re-derivation is only sound when the descriptor names the GLB solely
+ * through Package Version object references (`root`, `variants[].object`,
+ * `source`). A vehicle definition or any other sibling object that quotes the
+ * mesh by CID would be left pointing at bytes that no longer exist, so in that
+ * case nothing is rewritten and the publish is refused with the remedy
+ * (`helix glb add-normals`, rebuild the descriptor) or an explicit opt-out.
+ */
+export interface MissingNormalsOptions {
+    creaseAngleDeg?: number;
+    /** Receives one line per rewritten object. Defaults to stderr so a receipt on stdout stays machine-readable. */
+    log?: (message: string) => void;
+}
+export interface NormalsRewrite {
+    filename: string;
+    oldCid: string;
+    newCid: string;
+    oldBytes: number;
+    newBytes: number;
+    report: EnsureNormalsReport;
+}
+export declare class MissingNormalsError extends Error {
+    readonly filename: string;
+    readonly cid: string;
+    readonly fixablePrimitives: number;
+    constructor(filename: string, cid: string, fixablePrimitives: number, detail: string);
+}
+/**
+ * Adds smooth normals to every GLB object that lacks them, rewriting the
+ * Package Version and the object list in place. Returns what changed.
+ *
+ * Only inline (file) objects are examined: an object adopted by CID from an
+ * existing asset is already published and cannot be re-derived here.
+ */
+export declare function addMissingNormalsToPublication(packageVersion: ContinuumPackageVersion, objects: ContinuumObjectPublication[], options?: MissingNormalsOptions): Promise<NormalsRewrite[]>;

package/dist/continuum/missingNormals.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingNormalsError = void 0;
+exports.addMissingNormalsToPublication = addMissingNormalsToPublication;
+const node_crypto_1 = require("node:crypto");
+const smooth_normals_1 = require("../glb/smooth-normals");
+class MissingNormalsError extends Error {
+    filename;
+    cid;
+    fixablePrimitives;
+    constructor(filename, cid, fixablePrimitives, detail) {
+        super(`${filename} has ${fixablePrimitives} mesh primitive(s) with no NORMAL attribute, so it renders faceted everywhere, ` +
+            `and ${detail}. Fix the mesh first: \`helix glb add-normals ${filename}\`, rebuild the descriptor around the new file, ` +
+            'and publish again. Pass --allow-missing-normals only for a mesh that is deliberately flat-shaded.');
+        this.filename = filename;
+        this.cid = cid;
+        this.fixablePrimitives = fixablePrimitives;
+        this.name = 'MissingNormalsError';
+    }
+}
+exports.MissingNormalsError = MissingNormalsError;
+const GLB_MEDIA_TYPE = 'model/gltf-binary';
+const cidOf = (bytes) => `cid:sha256:${(0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex')}`;
+function isReference(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.cid === 'string' &&
+        typeof value.bytes === 'number');
+}
+/** Visits every Package Version object reference carrying `cid`, in place. */
+function replaceReferences(node, oldCid, next) {
+    if (Array.isArray(node))
+        return node.reduce((n, child) => n + replaceReferences(child, oldCid, next), 0);
+    if (typeof node !== 'object' || node === null)
+        return 0;
+    let replaced = 0;
+    if (isReference(node) && node.cid === oldCid) {
+        node.cid = next.cid;
+        node.bytes = next.bytes;
+        replaced++;
+    }
+    for (const value of Object.values(node))
+        replaced += replaceReferences(value, oldCid, next);
+    return replaced;
+}
+function mentions(bytes, text) {
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).includes(text);
+}
+/**
+ * Adds smooth normals to every GLB object that lacks them, rewriting the
+ * Package Version and the object list in place. Returns what changed.
+ *
+ * Only inline (file) objects are examined: an object adopted by CID from an
+ * existing asset is already published and cannot be re-derived here.
+ */
+async function addMissingNormalsToPublication(packageVersion, objects, options = {}) {
+    const log = options.log ?? ((message) => console.error(message));
+    const creaseAngleDeg = options.creaseAngleDeg ?? smooth_normals_1.DEFAULT_CREASE_ANGLE_DEG;
+    const rewrites = [];
+    for (const object of objects) {
+        if (object.source.kind !== 'inline')
+            continue;
+        const filename = object.source.filename ?? object.reference.cid;
+        if (object.reference.mediaType !== GLB_MEDIA_TYPE && !/\.glb$/i.test(filename))
+            continue;
+        const original = object.source.bytes;
+        const { bytes, report } = await (0, smooth_normals_1.ensureSmoothNormalsGlb)(original, { creaseAngleDeg });
+        if (!report.changed)
+            continue;
+        const oldCid = object.reference.cid;
+        const oldHex = oldCid.slice('cid:sha256:'.length);
+        const quotedBy = objects.find((other) => other !== object && other.source.kind === 'inline' && mentions(other.source.bytes, oldHex));
+        if (quotedBy) {
+            throw new MissingNormalsError(filename, oldCid, report.fixable, `another object in this publication (${quotedBy.reference.role ?? quotedBy.reference.cid}) quotes the mesh by its CID, so it cannot be rewritten safely here`);
+        }
+        const next = { cid: cidOf(bytes), bytes: bytes.byteLength };
+        const references = replaceReferences(packageVersion, oldCid, next);
+        if (references === 0) {
+            throw new MissingNormalsError(filename, oldCid, report.fixable, 'the Package Version does not reference it as root, variant or source, so the descriptor cannot be re-derived safely here');
+        }
+        object.reference = { ...object.reference, cid: next.cid, bytes: next.bytes };
+        object.source = { ...object.source, bytes };
+        const closure = packageVersion.expectedClosure;
+        if (closure)
+            closure.totalBytes += next.bytes - original.byteLength;
+        rewrites.push({
+            filename,
+            oldCid,
+            newCid: next.cid,
+            oldBytes: original.byteLength,
+            newBytes: next.bytes,
+            report,
+        });
+        log(`✔ ${filename}: ${report.fixable} primitive(s) had no NORMAL; wrote smooth normals ` +
+            `(crease ${creaseAngleDeg}°, ${original.byteLength} → ${next.bytes} bytes, ${oldCid.slice(0, 22)}… → ${next.cid.slice(0, 22)}…)`);
+    }
+    return rewrites;
+}
+//# sourceMappingURL=missingNormals.js.map

package/dist/continuum/missingNormals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missingNormals.js","sourceRoot":"","sources":["../../src/continuum/missingNormals.ts"],"names":[],"mappings":"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"}

package/dist/continuum/objectUpload.d.ts

@@ -0,0 +1,64 @@
+import { type HelixApi } from '../api';
+export declare const CONTINUUM_OBJECT_UPLOAD_MAX_BYTES: number;
+export declare const CONTINUUM_INLINE_OBJECT_MAX_BYTES: number;
+/** Advertised maximum for the dedicated reviewed-Unreal large lane. */
+export declare const CONTINUUM_LARGE_OBJECT_MAX_BYTES: number;
+/** Per-part PUT deadline. A timeout is a transient failure: the checkpoint is kept. */
+export declare const CONTINUUM_LARGE_PART_TIMEOUT_MS: number;
+interface Receipt {
+    contentId: string;
+    sizeBytes: number;
+    mediaType: string;
+    filename: string;
+    audience: 'private' | 'public';
+}
+/** Local bytes use the verified binary ingestion flow above the inline endpoint's small JSON-body limit. */
+export declare function stageContinuumObject(api: HelixApi, input: {
+    bytes: Uint8Array;
+    filename: string;
+    mediaType: string;
+    audience?: 'private' | 'public';
+}): Promise<unknown>;
+export type ContinuumLargeUploadDeps = {
+    /** Durable directory for the resumable intent token. Defaults to ~/.helix. */
+    stateDirectory?: string;
+    /**
+     * Stable checkpoint scope. Defaults to the API origin plus a non-reversible
+     * fingerprint of the caller's credential, so a signed intent token can never
+     * be reused against another account or server. The raw bearer is never stored.
+     */
+    scope?: string;
+    partTimeoutMs?: number;
+    onProgress?: (uploadedBytes: number, totalBytes: number) => void;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+};
+export interface ContinuumLargeUploadIntentResponse {
+    uploadId: string;
+    uploadToken: string;
+    expiresAt: string;
+    partSizeBytes: number;
+    partCount: number;
+    parts: {
+        partNumber: number;
+        partUrl: string;
+    }[];
+    receipt: Receipt;
+}
+/** Stream a file once to get its exact size and SHA-256 with bounded memory. */
+export declare function sha256File(path: string): Promise<{
+    sha256: string;
+    sizeBytes: number;
+}>;
+export declare function stageContinuumLargeObjectFromFile(api: HelixApi, input: {
+    path: string;
+    filename: string;
+    mediaType: string;
+    audience?: 'private' | 'public';
+    sha256?: string;
+    sizeBytes?: number;
+}, deps?: ContinuumLargeUploadDeps): Promise<Receipt & {
+    cid: string;
+    bytes: number;
+}>;
+export {};