@dstorage-tech/dstorage-sdk 0.0.4

package/dist/errors.d.mts

@@ -0,0 +1,117 @@
+export { StorageErrorCode } from '@dstorage/storage/errors';
+export { ChainErrorCode } from '@dstorage/chain/errors';
+import { StorageProviderName } from './types.js';
+
+declare class DStorageError extends Error {
+    readonly code: number;
+    readonly httpStatus?: number;
+    constructor(code: number, message: string, options?: ErrorOptions & {
+        httpStatus?: number;
+    });
+}
+declare function isDStorageError(err: unknown): err is DStorageError;
+declare const CryptoErrorCode: {
+    readonly WEBCRYPTO_NOT_AVAILABLE: 12000;
+    readonly BASE64URL_INVALID: 12001;
+    readonly MISSING_KEY_INPUT: 12002;
+    readonly MNEMONIC_TOO_SHORT: 12003;
+    readonly SEED_INVALID_LENGTH: 12004;
+    readonly MNEMONIC_INVALID: 12005;
+    readonly HEX_ODD_LENGTH: 12006;
+    readonly HEX_INVALID_CHARS: 12007;
+    readonly DEK_INVALID_LENGTH: 12008;
+    readonly WRAP_KEK_INVALID_LENGTH: 12009;
+    readonly UNWRAP_KEK_INVALID_LENGTH: 12010;
+    readonly ENVELOPE_EMPTY_WRAPPERS: 12011;
+    readonly XCHACHA_INVALID_STORAGE_ID_LEN: 12012;
+    readonly XCHACHA_PAYLOAD_MALFORMED: 12013;
+    readonly XCHACHA_STORAGE_ID_MALFORMED: 12014;
+    readonly MLKEM_SEED_INVALID_LENGTH: 12015;
+    readonly MLKEM_MISSING_CIPHERTEXT: 12016;
+    readonly MLKEM_UNKNOWN_ALGORITHM: 12017;
+    readonly MLKEM_UNKNOWN_VARIANT: 12018;
+};
+type CryptoErrorCode = (typeof CryptoErrorCode)[keyof typeof CryptoErrorCode];
+
+/**
+ * @dstorage/core — types.ts
+ * Top-level types for the dStorage SDK public API.
+ */
+
+/**
+ * Payload included in both `StorePartialError.recovery` and the `"stored"`
+ * phase of `StoreProgress`. Contains enough information to retry a failed
+ * chain write via `registerReference()` without re-uploading.
+ *
+ * `keyEnvelope` is the DEK encrypted under the user's KEK — safe to persist
+ * (e.g. in localStorage or a database). It is `undefined` for public uploads
+ * since their on-chain reference does not depend on a content DEK.
+ */
+interface StoreRecovery {
+    storageId: string;
+    /** Storage provider that holds the content — required by registerReference(). */
+    storageProvider: StorageProviderName;
+    keyEnvelope: string | undefined;
+    /**
+     * BLAKE3 hash of the ciphertext bytes stored at `storageId`, hex-encoded (64 chars).
+     * Pass to `registerReference()` to preserve the on-chain integrity check on the recovered reference.
+     */
+    contentHash?: string;
+}
+
+declare const CoreErrorCode: {
+    readonly METADATA_WITH_PUBLIC_UPLOAD: 10001;
+    readonly UPLOAD_NO_PROVIDERS: 10002;
+    readonly PUBLIC_UPLOAD_REQUIRES_SEED_PROVIDER: 10003;
+    readonly CHAIN_WRITE_FAILED: 10004;
+    readonly REGISTER_REF_REQUIRES_CHAIN: 10010;
+    readonly REGISTER_REF_REQUIRES_ENCRYPTION: 10011;
+    readonly UPDATE_UPLOAD_REQUIRES_CHAIN: 10020;
+    readonly UPDATE_UPLOAD_NOT_SUPPORTED: 10021;
+    readonly UPDATE_UPLOAD_REQUIRES_ENCRYPTION: 10022;
+    readonly ROTATE_KEYS_REQUIRES_CHAIN: 10023;
+    readonly ROTATE_KEYS_NOT_SUPPORTED: 10024;
+    readonly ROTATE_KEYS_REQUIRES_ENCRYPTION: 10025;
+    readonly DECRYPT_NO_PROVIDERS: 10030;
+    readonly DECRYPT_ENVELOPE_EMPTY: 10031;
+    readonly DECRYPT_ENVELOPE_MALFORMED: 10032;
+    readonly DECRYPT_NO_WRAPPER_MATCHED: 10033;
+    readonly UNWRAP_DEK_NO_PROVIDERS: 10034;
+    readonly UNWRAP_DEK_ENVELOPE_EMPTY: 10035;
+    readonly UNWRAP_DEK_ENVELOPE_MALFORMED: 10036;
+    readonly UNWRAP_DEK_NO_WRAPPER_MATCHED: 10037;
+    readonly DECRYPT_PAYLOAD_FAILED: 10038;
+    readonly RETRIEVE_BY_REF_ID_REQUIRES_CHAIN: 10050;
+    readonly REF_NOT_FOUND: 10051;
+    readonly STORAGE_ADAPTER_MISMATCH: 10052;
+    readonly RETRIEVE_BY_REF_ID_ENVELOPE_EMPTY: 10053;
+    readonly CONTENT_HASH_MISMATCH: 10054;
+    readonly LIST_REFS_REQUIRES_CHAIN: 10060;
+    readonly LIST_REFS_NOT_SUPPORTED: 10061;
+    readonly REMOVE_REF_REQUIRES_CHAIN: 10070;
+    readonly REMOVE_REF_NOT_SUPPORTED: 10071;
+    readonly META_TX_REQUIRES_ENCRYPTION: 10080;
+    readonly PREPARE_UPLOAD_NO_PROVIDERS: 10081;
+    readonly MANIFEST_INVALID_STRUCTURE: 10090;
+    readonly MANIFEST_CHUNK_COUNT_MISMATCH: 10091;
+    readonly MANIFEST_NOT_CONTIGUOUS: 10092;
+    readonly DECRYPT_CHUNK_FAILED: 10093;
+    readonly CHUNK_OVERFLOWS_TOTAL_SIZE: 10094;
+    readonly REASSEMBLY_SIZE_MISMATCH: 10095;
+    readonly NOT_INITIALIZED: 10100;
+    readonly META_TX_UNKNOWN_STEP: 10200;
+    readonly UNKNOWN_ERROR: 10999;
+};
+type CoreErrorCode = (typeof CoreErrorCode)[keyof typeof CoreErrorCode];
+/**
+ * Thrown when `store()` succeeds at the storage layer but fails to write the
+ * on-chain reference. The content is permanently on the storage network — use
+ * `err.recovery` with `registerReference()` to retry only the chain write.
+ */
+declare class StorePartialError extends DStorageError {
+    readonly recovery: StoreRecovery;
+    constructor(recovery: StoreRecovery);
+}
+declare function isStorePartialError(err: unknown): err is StorePartialError;
+
+export { CoreErrorCode, CryptoErrorCode, DStorageError, StorePartialError, isDStorageError, isStorePartialError };

package/dist/errors.d.ts

@@ -0,0 +1,117 @@
+export { StorageErrorCode } from '@dstorage/storage/errors';
+export { ChainErrorCode } from '@dstorage/chain/errors';
+import { StorageProviderName } from './types.js';
+
+declare class DStorageError extends Error {
+    readonly code: number;
+    readonly httpStatus?: number;
+    constructor(code: number, message: string, options?: ErrorOptions & {
+        httpStatus?: number;
+    });
+}
+declare function isDStorageError(err: unknown): err is DStorageError;
+declare const CryptoErrorCode: {
+    readonly WEBCRYPTO_NOT_AVAILABLE: 12000;
+    readonly BASE64URL_INVALID: 12001;
+    readonly MISSING_KEY_INPUT: 12002;
+    readonly MNEMONIC_TOO_SHORT: 12003;
+    readonly SEED_INVALID_LENGTH: 12004;
+    readonly MNEMONIC_INVALID: 12005;
+    readonly HEX_ODD_LENGTH: 12006;
+    readonly HEX_INVALID_CHARS: 12007;
+    readonly DEK_INVALID_LENGTH: 12008;
+    readonly WRAP_KEK_INVALID_LENGTH: 12009;
+    readonly UNWRAP_KEK_INVALID_LENGTH: 12010;
+    readonly ENVELOPE_EMPTY_WRAPPERS: 12011;
+    readonly XCHACHA_INVALID_STORAGE_ID_LEN: 12012;
+    readonly XCHACHA_PAYLOAD_MALFORMED: 12013;
+    readonly XCHACHA_STORAGE_ID_MALFORMED: 12014;
+    readonly MLKEM_SEED_INVALID_LENGTH: 12015;
+    readonly MLKEM_MISSING_CIPHERTEXT: 12016;
+    readonly MLKEM_UNKNOWN_ALGORITHM: 12017;
+    readonly MLKEM_UNKNOWN_VARIANT: 12018;
+};
+type CryptoErrorCode = (typeof CryptoErrorCode)[keyof typeof CryptoErrorCode];
+
+/**
+ * @dstorage/core — types.ts
+ * Top-level types for the dStorage SDK public API.
+ */
+
+/**
+ * Payload included in both `StorePartialError.recovery` and the `"stored"`
+ * phase of `StoreProgress`. Contains enough information to retry a failed
+ * chain write via `registerReference()` without re-uploading.
+ *
+ * `keyEnvelope` is the DEK encrypted under the user's KEK — safe to persist
+ * (e.g. in localStorage or a database). It is `undefined` for public uploads
+ * since their on-chain reference does not depend on a content DEK.
+ */
+interface StoreRecovery {
+    storageId: string;
+    /** Storage provider that holds the content — required by registerReference(). */
+    storageProvider: StorageProviderName;
+    keyEnvelope: string | undefined;
+    /**
+     * BLAKE3 hash of the ciphertext bytes stored at `storageId`, hex-encoded (64 chars).
+     * Pass to `registerReference()` to preserve the on-chain integrity check on the recovered reference.
+     */
+    contentHash?: string;
+}
+
+declare const CoreErrorCode: {
+    readonly METADATA_WITH_PUBLIC_UPLOAD: 10001;
+    readonly UPLOAD_NO_PROVIDERS: 10002;
+    readonly PUBLIC_UPLOAD_REQUIRES_SEED_PROVIDER: 10003;
+    readonly CHAIN_WRITE_FAILED: 10004;
+    readonly REGISTER_REF_REQUIRES_CHAIN: 10010;
+    readonly REGISTER_REF_REQUIRES_ENCRYPTION: 10011;
+    readonly UPDATE_UPLOAD_REQUIRES_CHAIN: 10020;
+    readonly UPDATE_UPLOAD_NOT_SUPPORTED: 10021;
+    readonly UPDATE_UPLOAD_REQUIRES_ENCRYPTION: 10022;
+    readonly ROTATE_KEYS_REQUIRES_CHAIN: 10023;
+    readonly ROTATE_KEYS_NOT_SUPPORTED: 10024;
+    readonly ROTATE_KEYS_REQUIRES_ENCRYPTION: 10025;
+    readonly DECRYPT_NO_PROVIDERS: 10030;
+    readonly DECRYPT_ENVELOPE_EMPTY: 10031;
+    readonly DECRYPT_ENVELOPE_MALFORMED: 10032;
+    readonly DECRYPT_NO_WRAPPER_MATCHED: 10033;
+    readonly UNWRAP_DEK_NO_PROVIDERS: 10034;
+    readonly UNWRAP_DEK_ENVELOPE_EMPTY: 10035;
+    readonly UNWRAP_DEK_ENVELOPE_MALFORMED: 10036;
+    readonly UNWRAP_DEK_NO_WRAPPER_MATCHED: 10037;
+    readonly DECRYPT_PAYLOAD_FAILED: 10038;
+    readonly RETRIEVE_BY_REF_ID_REQUIRES_CHAIN: 10050;
+    readonly REF_NOT_FOUND: 10051;
+    readonly STORAGE_ADAPTER_MISMATCH: 10052;
+    readonly RETRIEVE_BY_REF_ID_ENVELOPE_EMPTY: 10053;
+    readonly CONTENT_HASH_MISMATCH: 10054;
+    readonly LIST_REFS_REQUIRES_CHAIN: 10060;
+    readonly LIST_REFS_NOT_SUPPORTED: 10061;
+    readonly REMOVE_REF_REQUIRES_CHAIN: 10070;
+    readonly REMOVE_REF_NOT_SUPPORTED: 10071;
+    readonly META_TX_REQUIRES_ENCRYPTION: 10080;
+    readonly PREPARE_UPLOAD_NO_PROVIDERS: 10081;
+    readonly MANIFEST_INVALID_STRUCTURE: 10090;
+    readonly MANIFEST_CHUNK_COUNT_MISMATCH: 10091;
+    readonly MANIFEST_NOT_CONTIGUOUS: 10092;
+    readonly DECRYPT_CHUNK_FAILED: 10093;
+    readonly CHUNK_OVERFLOWS_TOTAL_SIZE: 10094;
+    readonly REASSEMBLY_SIZE_MISMATCH: 10095;
+    readonly NOT_INITIALIZED: 10100;
+    readonly META_TX_UNKNOWN_STEP: 10200;
+    readonly UNKNOWN_ERROR: 10999;
+};
+type CoreErrorCode = (typeof CoreErrorCode)[keyof typeof CoreErrorCode];
+/**
+ * Thrown when `store()` succeeds at the storage layer but fails to write the
+ * on-chain reference. The content is permanently on the storage network — use
+ * `err.recovery` with `registerReference()` to retry only the chain write.
+ */
+declare class StorePartialError extends DStorageError {
+    readonly recovery: StoreRecovery;
+    constructor(recovery: StoreRecovery);
+}
+declare function isStorePartialError(err: unknown): err is StorePartialError;
+
+export { CoreErrorCode, CryptoErrorCode, DStorageError, StorePartialError, isDStorageError, isStorePartialError };