arkiv-images 0.1.1 → 0.1.2

package/AGENTS.md

@@ -1,29 +1,29 @@
-# Integrating arkiv-images
-
-This is the consumer guide; it is included in npm. Read [README.md](README.md) explicitly for the public API, runnable examples, dependency versions, limits, data model and recovery behavior. This guide does not replace it.
-
-## Ask the developer
-
-- Local inspection, existing-image retrieval, or a new public upload? The first needs no network; retrieval needs the image key and explicit testnet; only writes need a signing wallet and test funds.
-- Which testnet/RPC and Entity Expiration in blocks? Use the actually tested combination in README. Never infer production or mainnet compatibility.
-- Are the **original image bytes, filename and metadata** safe to make public? The tool keeps EXIF/GPS unchanged. If privacy is required, stop: encryption is a different tool, and this one does not solve it.
-- For retrieval, ask for an image key and optionally an independently trusted SHA-256. Do not confuse an image entity key with its file-manifest key.
-- For browser writes, ask the developer to connect their own MetaMask/Rabby account and confirm transactions. For Node, ask them to configure their key locally as described in README; never request a private key in chat. Provider access keys come from the provider/Hub links there.
-
-Local `inspectImage` and `planImage` can be integrated immediately while legitimate network/product questions remain open.
-
-## Preserve these invariants
-
-- Import only the public package API; do not copy its storage, image validation or chunking implementation into the app. Use the released npm version in consumers.
-- Binary image bytes belong in the payload; queryable metadata belongs in typed attributes. The package schema and dependency own these decisions. Do not search inside payloads or substitute SQL for SDK query syntax.
-- Keep the testnet checks, size limits and integrity validation. No partial image, no silent lossy conversion, no pretending expiration erases history.
-- A browser consumer must fully decode before upload and after retrieval, then render only the allowed raster MIME as an image. Manage/revoke Blob URLs. Filenames are text, not markup.
-- Confirm completion only after `storeImage` resolves. Preserve confirmed hashes/manifest keys on failure, serialize writes, and do not automatically retry ambiguous writes. Check wallet account/network before every signature, including the final root write.
-- Keep secrets out of source, logs, packages and browser bundles. Do not display raw SDK/provider errors. No server signer for the sample.
-- No independent mutation/extension/ownership transfer of the parts. Root existence alone does not prove its referenced chunks are still available.
-
-## Verify the integration
-
-Follow the README in a new consumer. Import the public TypeScript types, run the exact local example, then test the requested network flow. Compare original and retrieved bytes and digest. Test unsupported/oversized files, wrong network, absent key, rejected writes, missing/corrupt chunks and browser decode errors. Distinguish mocked RPC, packed candidate and installed npm release. For UI, render small/medium/large widths and inspect loading, empty and error states. Record versions, network, actual results and unverified items.
-
-Source maintainers: keep this guide, CLAUDE.md and verification in the publication allowlist. Sample instructions and agent guide live in `sample/`, linked from README; explicitly give them to consumer agents. No new skills, MCP, generator, encryption or media-management features belong to this tool.
+# Integrating arkiv-images
+
+This is the consumer guide; it is included in npm. Read [README.md](README.md) explicitly for the public API, runnable examples, dependency versions, limits, data model and recovery behavior. This guide does not replace it.
+
+## Ask the developer
+
+- Local inspection, existing-image retrieval, or a new public upload? The first needs no network; retrieval needs the image key and explicit testnet; only writes need a signing wallet and test funds.
+- Which testnet/RPC and Entity Expiration in blocks? Use the actually tested combination in README. Never infer production or mainnet compatibility.
+- Are the **original image bytes, filename and metadata** safe to make public? The tool keeps EXIF/GPS unchanged. If privacy is required, stop: encryption is a different tool, and this one does not solve it.
+- For retrieval, ask for an image key and optionally an independently trusted SHA-256. Do not confuse an image entity key with its file-manifest key.
+- For browser writes, ask the developer to connect their own MetaMask/Rabby account and confirm transactions. For Node, ask them to configure their key locally as described in README; never request a private key in chat. Provider access keys come from the provider/Hub links there.
+
+Local `inspectImage` and `planImage` can be integrated immediately while legitimate network/product questions remain open.
+
+## Preserve these invariants
+
+- Import only the public package API; do not copy its storage, image validation or chunking implementation into the app. Use the released npm version in consumers.
+- Binary image bytes belong in the payload; queryable metadata belongs in typed attributes. The package schema and dependency own these decisions. Do not search inside payloads or substitute SQL for SDK query syntax.
+- Keep the testnet checks, size limits and integrity validation. No partial image, no silent lossy conversion, no pretending expiration erases history.
+- A browser consumer must fully decode before upload and after retrieval, then render only the allowed raster MIME as an image. Manage/revoke Blob URLs. Filenames are text, not markup.
+- Confirm completion only after `storeImage` resolves. Preserve confirmed hashes/manifest keys on failure, serialize writes, and do not automatically retry ambiguous writes. Check wallet account/network before every signature, including the final root write.
+- Keep secrets out of source, logs, packages and browser bundles. Do not display raw SDK/provider errors. No server signer for the sample.
+- No independent mutation/extension/ownership transfer of the parts. Root existence alone does not prove its referenced chunks are still available.
+
+## Verify the integration
+
+Follow the README in a new consumer. Import the public TypeScript types, run the exact local example, then test the requested network flow. Compare original and retrieved bytes and digest. Test unsupported/oversized files, wrong network, absent key, rejected writes, missing/corrupt chunks and browser decode errors. Distinguish mocked RPC, packed candidate and installed npm release. For UI, render small/medium/large widths and inspect loading, empty and error states. Record versions, network, actual results and unverified items.
+
+Source maintainers: keep this guide, CLAUDE.md and verification in the publication allowlist. Sample instructions and agent guide live in `sample/`, linked from README; explicitly give them to consumer agents. No new skills, MCP, generator, encryption or media-management features belong to this tool.

package/CLAUDE.md

@@ -1 +1 @@
-Read [AGENTS.md](AGENTS.md) for the consumer integration guide and invariants.
+Read [AGENTS.md](AGENTS.md) for the consumer integration guide and invariants.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Santiago Trujillo Zuluaga
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Santiago Trujillo Zuluaga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,18 +4,20 @@ Store a public PNG or JPEG as queryable Arkiv entities, then retrieve and displa
 
 **These packages are intended for testnet use.**
 
-Version **0.1.1**. See [verification](docs/verification.md) for release evidence and [the npm registry](https://www.npmjs.com/package/arkiv-images/v/0.1.1) for availability. A locally packed artifact is not a published release.
+Version **0.1.2** adds SDK **0.8.1** support and depends on `arkiv-chunking` **0.1.1**. The immutable [0.1.1 archive](https://www.npmjs.com/package/arkiv-images/v/0.1.1) uses SDK 0.8.0 and chunking 0.1.0. Check both registry versions before installing; see [verification](docs/verification.md) for source checks and dated evidence.
 
 ## Install and inspect an image
 
-ESM, Node **22.10+** with Web Crypto, or a current browser on HTTPS/localhost. The tested dependency combination is SDK **0.8.0**, viem **2.56.3**, `arkiv-chunking` **0.1.0**, Node **22.22.3**. SDK 0.7 and older are incompatible. Other SDK versions, runtimes and networks are not claimed tested; see the evidence matrix below.
+ESM, Node **22.10+** with Web Crypto, or a current browser on HTTPS/localhost. The candidate is tested with SDK **0.8.1**, viem **2.56.3**, `arkiv-chunking` **0.1.1**, Node **22.22.3**. Its SDK peer range is `>=0.8.1 <0.9`; other releases in that range and other runtimes are untested.
+
+Build and pack the chunking candidate first, then this package. Install both resulting tarballs in a clean consumer:
 
 ```sh
 mkdir image-consumer
 cd image-consumer
 npm init -y
 npm pkg set type=module
-npm install --save-exact arkiv-images@0.1.1 @arkiv-network/sdk@0.8.0 viem@2.56.3
+npm install --save-exact /absolute/path/to/arkiv-chunking-0.1.1.tgz /absolute/path/to/arkiv-images-0.1.2.tgz @arkiv-network/sdk@0.8.1 viem@2.56.3
 ```
 
 Create `inspect.mjs`:
@@ -175,7 +177,7 @@ All functions and TypeScript types are exported from `arkiv-images`. Do not impo
 
 The inline threshold leaves room for attributes and transaction framing. The commonly cited 131,072-byte payload ceiling is **not** an image budget: the complete transaction also has a size limit. [Verification](docs/verification.md) records actual encoded sizes and which boundaries were submitted on Tiramisu. JPEG/PNG are already compressed image formats; converting to PDF or base64 does not remove the storage constraint. A photo's size varies with dimensions, detail and encoding; the sample measures the selected file rather than guessing from megapixels.
 
-**No encryption, metadata stripping, resizing or recompression.** The tool preserves the exact original bytes, including EXIF/GPS, embedded thumbnails and names. Everyone with read access to the public network can retrieve them. The sample requires acknowledgement before uploading. Use synthetic/non-sensitive images. Expiration removes entities from current queries; it does **not** erase historical bytes or copies. This tool offers no read authorization and does not claim confidentiality.
+**No encryption, metadata stripping, resizing or recompression.** The tool preserves the exact original bytes, including EXIF/GPS, embedded thumbnails and names. Everyone with read access to the public network can retrieve them. Use synthetic/non-sensitive images. Expiration removes entities from current queries; it does **not** erase historical bytes or copies. This tool offers no read authorization and does not claim confidentiality.
 
 The package performs bounded container checks, not a complete PNG CRC/JPEG entropy decode, antivirus scan or content moderation. A file can pass header checks and still fail full decoding. JPEGs must end at their end-of-image marker; files with trailing padding are rejected even if some decoders accept them. Export such files as a standard JPEG before uploading. The sample calls `createImageBitmap` both before writes and after retrieval. Consumers rendering images must also handle decode failures. Never serve uploaded bytes as HTML or SVG, and never trust a filename as markup.
 
@@ -187,6 +189,8 @@ No multi-transaction atomicity, automatic write retries/resume, deduplication, d
 
 ## Troubleshooting
 
+`retrieveImage` can throw either `ImageStorageError` or the exported `ChunkingError`; chunk failures are not members of `ImageErrorCode`. Handle both classes and use their safe `code`/`message` fields. Do not log the raw error or `cause`, which can contain provider secrets.
+
 | Symptom | Resolution |
 |---|---|
 | `INVALID_IMAGE` / browser decode error | Use a valid static PNG or baseline/progressive JPEG within the pixel limit. Changing an extension does not convert a file. |
@@ -204,6 +208,8 @@ No multi-transaction atomicity, automatic write retries/resume, deduplication, d
 
 ## Sample, agent guides and development
 
+- [Live sample](https://arkiv-images-example.vercel.app), consuming `arkiv-images@0.1.1` from npm. [Deployment verification](docs/sample-review-v3.md) distinguishes real Tiramisu reads from controlled wallet tests.
+- Listed in the Hub as [ARKIV-STORE-IMAGES](https://stage.hub.arkiv.network/tools#tool-arkiv-store-images). The npm package name remains `arkiv-images`.
 - [Sample README](https://github.com/SantiagoDevRel/arkiv-images/blob/feat/image-storage/sample/README.md): source checkout, localhost commands and visitor-wallet flow.
 - [Consumer AGENTS.md](AGENTS.md) and [sample AGENTS.md](https://github.com/SantiagoDevRel/arkiv-images/blob/feat/image-storage/sample/AGENTS.md). Give these guides to your agent explicitly. It will not necessarily read files under `node_modules` automatically. Each CLAUDE.md points to the corresponding AGENTS.md.
 - [Verification](docs/verification.md): exact runtimes, dependency versions, simulated vs real checks, publication and unresolved gates.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { type ChunkingPublicClient, type ChunkingWalletClient, type Progress } from 'arkiv-chunking';
 import type { Hex } from 'viem';
-export declare const VERSION = "0.1.1";
+export declare const VERSION = "0.1.2";
 export declare const IMAGE_TYPE = "arkiv-images/v1";
 export declare const INLINE_MAX_BYTES = 120000;
 export declare const MAX_IMAGE_BYTES: number;

package/dist/index.js

@@ -2,7 +2,7 @@ import { ExpirationTime } from '@arkiv-network/sdk';
 import { bytes32, key, str, u64 } from '@arkiv-network/sdk/attr';
 import { eq } from '@arkiv-network/sdk/query';
 import { uploadFile, downloadFile, hashFile, ChunkingError, DEFAULT_CHUNK_BYTES } from 'arkiv-chunking';
-export const VERSION = '0.1.1';
+export const VERSION = '0.1.2';
 export const IMAGE_TYPE = 'arkiv-images/v1';
 export const INLINE_MAX_BYTES = 120_000;
 export const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
@@ -107,7 +107,12 @@ function filenameValid(filename) {
 async function checkNetwork(client, wallet) {
     if (!client.chain?.testnet || await client.getChainId() !== client.chain.id)
         fail('NETWORK_MISMATCH', 'Configure an explicit testnet matching the RPC.');
-    if (wallet && (!wallet.account || !wallet.chain?.testnet || wallet.chain.id !== client.chain.id || Number(await wallet.transport.request({ method: 'eth_chainId' })) !== client.chain.id))
+    if (!wallet)
+        return;
+    if (!wallet.account || !wallet.chain?.testnet || wallet.chain.id !== client.chain.id)
+        fail('NETWORK_MISMATCH', 'The wallet and RPC must use the same explicit testnet.');
+    const walletChainId = await wallet.transport.request({ method: 'eth_chainId' });
+    if (typeof walletChainId !== 'string' || !/^0x[0-9a-f]+$/i.test(walletChainId) || Number(BigInt(walletChainId)) !== client.chain.id)
         fail('NETWORK_MISMATCH', 'The wallet and RPC must use the same explicit testnet.');
 }
 /** Preserve original file bytes. All bytes, metadata and wallet addresses are public. Never retries writes. */