{"id":15734,"library":"object-storage-client","title":"Metorial Object Storage Client","description":"The `object-storage-client` package provides a TypeScript and JavaScript client library for programmatic interaction with the Metorial Object Storage Service. It offers a comprehensive, promise-based API for managing buckets and objects, including creation, listing, uploading, downloading, and deletion. The current stable version, 0.2.5, indicates it is in early development and pre-1.0 stability, meaning minor versions might introduce breaking changes. Its key differentiators include strong TypeScript support, a direct interface to the Metorial Object Storage backend (which itself supports multiple storage backends like local filesystem, AWS S3, Google Cloud Storage, and Azure Blob Storage), and a straightforward API for asynchronous operations. This client is specifically designed for the Metorial ecosystem, which aims to connect AI agents to various tools and services.","status":"active","version":"0.2.5","language":"javascript","source_language":"en","source_url":"https://github.com/metorial/object-storage","tags":["javascript","object-storage","s3","client","typescript"],"install":[{"cmd":"npm install object-storage-client","lang":"bash","label":"npm"},{"cmd":"yarn add object-storage-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add object-storage-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library is written in TypeScript and primarily targets ESM environments; use named imports. Direct CommonJS require() may lead to incorrect resolution or require default property access.","wrong":"const ObjectStorageClient = require('object-storage-client').ObjectStorageClient;","symbol":"ObjectStorageClient","correct":"import { ObjectStorageClient } from 'object-storage-client';"},{"note":"This is a named export for the custom error class used for API-specific errors, allowing detailed error handling based on status codes. Do not use a default import.","wrong":"import ObjectStorageError from 'object-storage-client';","symbol":"ObjectStorageError","correct":"import { ObjectStorageError } from 'object-storage-client';"}],"quickstart":{"code":"import { ObjectStorageClient, ObjectStorageError } from 'object-storage-client';\n\nconst client = new ObjectStorageClient('http://localhost:8080');\n\nasync function runObjectStorageDemo() {\n  try {\n    // Create a bucket\n    const bucketName = 'my-unique-test-bucket-' + Date.now();\n    console.log(`Attempting to create bucket: ${bucketName}`);\n    const bucket = await client.createBucket(bucketName);\n    console.log(`Created bucket: ${bucket.name}`);\n\n    // Upload an object\n    const data = Buffer.from('Hello, Object Storage World!');\n    const objectKey = 'hello.txt';\n    console.log(`Uploading object '${objectKey}' to '${bucketName}'`);\n    const obj = await client.putObject(\n      bucketName,\n      objectKey,\n      data,\n      'text/plain',\n      { author: 'AI-Agent' }\n    );\n    console.log(`Uploaded object: ${obj.key} (ETag: ${obj.etag})`);\n\n    // Download an object\n    console.log(`Downloading object '${objectKey}' from '${bucketName}'`);\n    const objData = await client.getObject(bucketName, objectKey);\n    console.log(`Downloaded ${objData.data.length} bytes. Content: ${objData.data.toString()}`);\n\n    // List objects\n    console.log(`Listing objects in '${bucketName}'`);\n    const objects = await client.listObjects(bucketName);\n    for (const item of objects) {\n      console.log(`- ${item.key}: ${item.size} bytes`);\n    }\n\n    // Delete object\n    console.log(`Deleting object '${objectKey}' from '${bucketName}'`);\n    await client.deleteObject(bucketName, objectKey);\n    console.log('Object deleted.');\n\n    // Delete bucket\n    console.log(`Deleting bucket: ${bucketName}`);\n    await client.deleteBucket(bucketName);\n    console.log('Bucket deleted.');\n\n  } catch (error) {\n    if (error instanceof ObjectStorageError) {\n      console.error(`Object Storage API Error: Status ${error.statusCode}, Message: ${error.message}`);\n    } else if (error instanceof Error) {\n      console.error(`Generic Error: ${error.message}`);\n    } else {\n      console.error('An unknown error occurred:', error);\n    }\n  }\n}\n\nrunObjectStorageDemo();","lang":"typescript","description":"This quickstart demonstrates the full lifecycle of object storage operations: creating a bucket, uploading a text file, downloading it, listing objects, and finally deleting both the object and the bucket. It also includes basic error handling for API-specific and generic errors."},"warnings":[{"fix":"Pin the exact version (e.g., `\"object-storage-client\": \"0.2.5\"`) in your `package.json` and manually review the project's GitHub releases for breaking changes before upgrading. Consider using a tool like `npm-check-updates` with a conservative update policy.","message":"As of version 0.2.5, this library is in pre-1.0 development. Breaking changes may be introduced in minor or even patch releases without strict adherence to semantic versioning until a stable 1.0.0 release is made. Users should pin exact versions and review changelogs carefully.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure your application is configured to interact with a Metorial Object Storage Service instance. If you need a client for a generic S3-compatible service, consider alternatives like `@aws-sdk/client-s3` or `minio`'s client library.","message":"This client is specifically designed for the Metorial Object Storage Service. While the service itself supports multiple backends (S3, GCS, Azure), this client does not offer a generic S3-compatible interface that works with *any* S3-compatible service directly. It communicates with the Metorial API, not a generic S3 endpoint.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Implement robust `try...catch` blocks that handle both `ObjectStorageError` for API responses and generic `Error` instances for underlying network or connection failures, as demonstrated in the quickstart example.","message":"Connection errors (e.g., server offline, wrong URL, network issues) will typically throw standard Node.js or browser `Error` objects (e.g., `ECONNREFUSED`, `FetchError`) rather than `ObjectStorageError`. The `ObjectStorageError` is reserved for successful HTTP requests that return an API-specific error from the Metorial service.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { ObjectStorageClient } from 'object-storage-client';` in your TypeScript/ESM files. If using CommonJS, consider transpiling your code to ESM or configuring your bundler (e.g., Webpack, Rollup) to correctly handle ESM module resolution for `object-storage-client`.","cause":"Attempting to use CommonJS `require()` or an incorrect import style in an ESM context or a bundler misconfiguration.","error":"TypeError: (0 , object_storage_client_1.ObjectStorageClient) is not a constructor"},{"fix":"Verify that the bucket name is correct and that the bucket exists before attempting object-level operations. If the bucket should exist, check the server-side logs for unexpected deletion or naming issues.","cause":"Attempting to perform an operation (like `getObject`, `deleteObject`) on a bucket that does not exist or has been deleted.","error":"Object Storage API Error: Status 404, Message: Bucket not found"},{"fix":"Ensure the Metorial Object Storage Service is running and accessible from where your client code is executing. Double-check the URL and port provided to the `ObjectStorageClient` constructor. If running in Docker, ensure port mappings are correct.","cause":"The Metorial Object Storage Service is not running or is not accessible at the specified endpoint (e.g., `http://localhost:8080`).","error":"Error: connect ECONNREFUSED 127.0.0.1:8080"}],"ecosystem":"npm"}