{"_id":"@atomiqlabs/storage-cosmosdb","name":"@atomiqlabs/storage-cosmosdb","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@atomiqlabs/storage-cosmosdb","version":"1.0.0","description":"Microsoft Azure CosmosDB storage implementation for atomiqlabs SDK","main":"./dist/index.js","types:":"./dist/index.d.ts","scripts":{"build":"npx -y -p typescript@4.9 tsc","test":"echo \"Error: no test specified\" && exit 1","build:ts4":"npx -p typescript@4.9 tsc --noEmit","build:ts5":"npx -p typescript@5.3 tsc --noEmit"},"keywords":["Solana","Bitcoin","Cross-chain","Cryptocurrency","Bridge","Trustless"],"author":{"name":"adambor"},"license":"ISC","dependencies":{"@azure/cosmos":"4.9.3"},"peerDependencies":{"@atomiqlabs/base":">=13.0.0 <14.0.0","@atomiqlabs/sdk":"^8.9.4"},"devDependencies":{"@types/node":"22.9.3","typescript":">=4"},"_id":"@atomiqlabs/storage-cosmosdb@1.0.0","gitHead":"dfbf8b3dc9c1fc75bd78690c59159684645be856","types":"./dist/index.d.ts","_nodeVersion":"24.9.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-o5J5TUFMSoT7T4Jo02OO7LT0ABISmNZx4dji81H5LB65tu3T9pR6HpHHwLg10wPBNueIn5tazpMSSTfjK1XTjg==","shasum":"5a8c0b3582c74ff62993a8a74b82e51a8eb35b0a","tarball":"https://registry.npmjs.org/@atomiqlabs/storage-cosmosdb/-/storage-cosmosdb-1.0.0.tgz","fileCount":24,"unpackedSize":107709,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFb+OF+fnKZe7QFA8dh4RmZ2EYaqv9rPseQmgyFOdS89AiEApbAw20G4nrqdZjMHnYJfEot4shFx4mgO7+4CpYPUtFU="}]},"_npmUser":{"name":"adambor","email":"adamborcany@gmail.com"},"directories":{},"maintainers":[{"name":"adambor","email":"adamborcany@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/storage-cosmosdb_1.0.0_1782472026890_0.6125098358363736"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-26T11:07:06.741Z","1.0.0":"2026-06-26T11:07:07.033Z","modified":"2026-06-26T11:07:07.266Z"},"maintainers":[{"name":"adambor","email":"adamborcany@gmail.com"}],"description":"Microsoft Azure CosmosDB storage implementation for atomiqlabs SDK","keywords":["Solana","Bitcoin","Cross-chain","Cryptocurrency","Bridge","Trustless"],"author":{"name":"adambor"},"license":"ISC","readme":"# @atomiqlabs/storage-cosmosdb\n\n`@atomiqlabs/storage-cosmosdb` is the Azure Cosmos DB-backed storage adapter for the Atomiq SDK in Node.js backend environments. The SDK uses browser IndexedDB by default. Backends, workers, and shared services need to provide storage implementations explicitly. This package provides those implementations on top of Azure Cosmos DB for NoSQL containers.\n\n## What this package provides\n\n- `CosmosDBSwapStorage`: persistent unified swap storage used by the SDK for swap records and indexed queries.\n- `CosmosDBSwapPatchStorage`: persistent unified swap storage that writes Cosmos DB patch operations for existing swap records when possible.\n- `CosmosDBStorageManager`: persistent storage manager used for chain-specific SDK stores.\n- `CosmosDBConcurrencyError`: error thrown when a Cosmos DB ETag-based concurrency check fails.\n\nEach storage instance uses one Cosmos DB container. Constructors take the container id, the Cosmos DB connection string, and an optional database name. The database name defaults to `Atomiq`.\n\n## When to use it\n\nUse this package when you run the Atomiq SDK in:\n\n- Node.js backend services\n- backend workers\n- Azure-specific runtimes such as Azure Functions or other serverless function apps\n- server-side deployments that need shared cloud persistence\n- environments where local SQLite files are not suitable\n\nDo not use this package from browser or React Native apps, because the Cosmos DB connection string must stay server-side. Browser apps usually use the SDK's default IndexedDB storage, and React Native apps can use `@atomiqlabs/storage-rn-async`.\n\n## Installation\n\n```bash\nnpm install @atomiqlabs/sdk @atomiqlabs/base @atomiqlabs/storage-cosmosdb\n```\n\nThis adapter uses `@azure/cosmos` under the hood. Your application needs access to an Azure Cosmos DB for NoSQL account and a connection string for that account.\n\n## Cosmos DB setup\n\nDuring SDK initialization, the adapter creates the configured database and containers if they do not already exist.\n\n- Swap storage containers use partition key `/id` and an indexing policy generated from the SDK's simple and composite swap indexes.\n- Chain storage manager containers use partition key `/id` with indexing disabled.\n- If you pre-create containers, configure them with the same partition key and compatible indexing policy.\n- Use stable container ids for each swap chain and chain-specific store. Changing a container id points the SDK at a different storage namespace.\n\n## SDK Usage\n\nPass `CosmosDBSwapStorage` as `swapStorage` and `CosmosDBStorageManager` as `chainStorageCtor` when creating the swapper.\n\n```typescript\nimport {BitcoinNetwork, SwapperFactory, TypedSwapper} from \"@atomiqlabs/sdk\";\nimport {CosmosDBStorageManager, CosmosDBSwapStorage} from \"@atomiqlabs/storage-cosmosdb\";\n\nconst connectionString = process.env.ATOMIQ_COSMOSDB_CONNECTION_STRING;\nif(connectionString == null) throw new Error(\"Missing ATOMIQ_COSMOSDB_CONNECTION_STRING\");\n\nconst chains = [SolanaInitializer, StarknetInitializer, CitreaInitializer] as const;\ntype SupportedChains = typeof chains;\n\nconst Factory = new SwapperFactory<SupportedChains>(chains);\n\nconst swapper: TypedSwapper<SupportedChains> = Factory.newSwapper({\n    chains: {\n        ...\n    },\n    bitcoinNetwork: BitcoinNetwork.MAINNET,\n    // In Node.js, provide persistent storage because the SDK's default\n    // browser storage implementation is IndexedDB.\n    swapStorage: chainId => new CosmosDBSwapStorage(\n        `ATQ_SWAPS_${chainId}`,\n        connectionString\n    ),\n    chainStorageCtor: name => new CosmosDBStorageManager(\n        `ATQ_STORE_${name}`,\n        connectionString\n    )\n});\n\nawait swapper.init();\n```\n\nTo use a custom database name, pass it as the third constructor argument:\n\n```typescript\nswapStorage: chainId => new CosmosDBSwapStorage(\n    `ATQ_SWAPS_${chainId}`,\n    connectionString,\n    \"MyAtomiqDatabase\"\n)\n```\n\n## Patch-based swap storage\n\n`CosmosDBSwapPatchStorage` has the same constructor shape as `CosmosDBSwapStorage`, plus an optional fourth `optimisticConcurrency` argument.\n\n```typescript\nimport {CosmosDBSwapPatchStorage} from \"@atomiqlabs/storage-cosmosdb\";\n\nswapStorage: chainId => new CosmosDBSwapPatchStorage(\n    `ATQ_SWAPS_${chainId}`,\n    connectionString,\n    \"Atomiq\",\n    true\n)\n```\n\nUse `CosmosDBSwapPatchStorage` when you want existing swap updates to be sent as Cosmos DB patch operations where possible. When `optimisticConcurrency` is `true`, patch, replace, and delete operations for previously loaded swaps include the loaded ETag and throw `CosmosDBConcurrencyError` if the document changed concurrently. The default is `false`.\n\n## Notes\n\n- `CosmosDBSwapStorage` stores one swap per Cosmos DB item and uses Cosmos DB indexes generated from the SDK-provided storage schema.\n- Swap containers and chain storage containers are separate. Use distinct, stable container ids for `swapStorage` and `chainStorageCtor`.\n- `CosmosDBConcurrencyError` includes the affected `itemIds` so callers can decide whether to retry, reload, or surface the conflict.\n- Persistence, availability, throughput, and backup behavior depend on the Azure Cosmos DB account configuration you choose.\n","readmeFilename":"README.md","_rev":"1-45b4c40342c4d8ea49fe0f7aef6ae264"}