@healthzkit/s3 0.0.1

package/README.md

@@ -0,0 +1,136 @@
+# @healthzkit/s3
+
+Amazon S3 **healthzkit** `HealthAdapter` helpers for AWS SDK v2 **[`aws-sdk`](https://github.com/aws/aws-sdk-js)** and v3 **[`@aws-sdk/client-s3`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/)**. Successful checks call `ListBuckets` and return `ok` with `metadata.latencyMs`, `metadata.bucketCount`, plus any fields from an optional `metadata` hook; failures return `fail` with the caught error.
+
+## Install
+
+```bash
+npm install @healthzkit/s3 healthzkit
+# plus one of:
+npm install aws-sdk
+npm install @aws-sdk/client-s3
+```
+
+Both SDKs are optional peers—install only the one you use.
+
+## Package entrypoints
+
+| Import              | Exports                                        |
+| ------------------- | ---------------------------------------------- |
+| `@healthzkit/s3`    | `s3V2Adapter`, `s3V3Adapter`, and option types |
+| `@healthzkit/s3/v2` | `s3V2Adapter` only                             |
+| `@healthzkit/s3/v3` | `s3V3Adapter` only                             |
+
+Use subpath imports when you want to avoid pulling the unused SDK into your bundle analysis path.
+
+## Shared options
+
+Both factories accept `BaseS3Options`:
+
+| Option     | Description                                                                                           |
+| ---------- | ----------------------------------------------------------------------------------------------------- |
+| `metadata` | Optional `(client) => Record<string, unknown>` (sync or async) merged into metadata with `latencyMs`. |
+
+Pass either `config` or an existing `client` (not both). The shape depends on the adapter (see below).
+
+## `s3V2Adapter` (`aws-sdk`)
+
+**Peer:** `aws-sdk` ≥ 2.
+
+Uses the v2 `S3` client and `listBuckets()`. Suitable for legacy services still on AWS SDK for JavaScript v2.
+
+### Config
+
+The adapter lazily imports `aws-sdk`, constructs `new AWS.S3(config)` once, and reuses it across checks.
+
+```ts
+import { createHealthKit } from "healthzkit";
+import { s3V2Adapter } from "@healthzkit/s3";
+
+const kit = createHealthKit({
+  checks: [
+    {
+      name: "s3",
+      type: ["readiness"],
+      adapter: s3V2Adapter({
+        config: { region: process.env.AWS_REGION ?? "us-east-1" },
+      }),
+    },
+  ],
+});
+```
+
+### Existing client
+
+```ts
+import AWS from "aws-sdk";
+import { s3V2Adapter } from "@healthzkit/s3/v2";
+
+const client = new AWS.S3({ region: "us-east-1" });
+
+const adapter = s3V2Adapter({
+  client,
+  metadata: () => ({ sdk: "v2" }),
+});
+```
+
+## `s3V3Adapter` (`@aws-sdk/client-s3`)
+
+**Peer:** `@aws-sdk/client-s3` ≥ 3.
+
+Uses `S3Client` and `ListBucketsCommand`. Prefer this for new code on AWS SDK for JavaScript v3.
+
+### Config
+
+The adapter lazily imports `@aws-sdk/client-s3`, constructs `new S3Client(config)` once, and reuses it across checks.
+
+```ts
+import { s3V3Adapter } from "@healthzkit/s3/v3";
+
+const adapter = s3V3Adapter({
+  config: { region: process.env.AWS_REGION ?? "us-east-1" },
+});
+```
+
+### Existing client
+
+```ts
+import { S3Client } from "@aws-sdk/client-s3";
+import { s3V3Adapter } from "@healthzkit/s3";
+
+const client = new S3Client({ region: "us-east-1" });
+
+const adapter = s3V3Adapter({
+  client,
+  metadata: async () => ({ sdk: "v3" }),
+});
+```
+
+## Check result
+
+On success:
+
+```json
+{
+  "status": "ok",
+  "metadata": { "latencyMs": 42, "bucketCount": 3 }
+}
+```
+
+On failure, `status` is `"fail"` and `error` is set (see [healthzkit](https://github.com/alasti-company/healthzkit) for how that rolls up into probe responses).
+
+## Scheduling
+
+For S3 buckets that should not be queried on every probe, pair these adapters with a **`schedule`** on the check so readiness reads cached results. See the **Scheduling** section in the `healthzkit` README.
+
+## Development
+
+From the monorepo root:
+
+```bash
+vp install
+vp test --filter @healthzkit/s3
+vp pack --filter @healthzkit/s3
+```
+
+See the repo root `AGENTS.md` for Vite+ / `vp` conventions.

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { S3V3AdapterOptions, s3V3Adapter } from "./v3.mjs";
+import { S3V2AdapterOptions, s3V2Adapter } from "./v2.mjs";
+export { type S3V2AdapterOptions, type S3V3AdapterOptions, s3V2Adapter, s3V3Adapter };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{s3V3Adapter as e}from"./v3.mjs";import{s3V2Adapter as t}from"./v2.mjs";export{t as s3V2Adapter,e as s3V3Adapter};

package/dist/shared-B-1hAtzF.mjs

@@ -0,0 +1 @@
+function e(e,t){return{status:`ok`,metadata:{...t,latencyMs:e}}}function t(e){return{status:`fail`,error:e instanceof Error?e:Error(String(e))}}export{e as n,t};

package/dist/shared-B3WTV2_N.d.mts

@@ -0,0 +1,13 @@
+import { HealthAdapter } from "healthzkit";
+
+//#region src/shared.d.ts
+type MetadataFn<TClient> = (client: TClient) => Promise<Record<string, unknown>> | Record<string, unknown>;
+interface BaseS3Options<TClient> {
+  /**
+   * Optional function to populate metadata in the check result.
+   * Receives the resolved client so you can run additional operations.
+   */
+  metadata?: MetadataFn<TClient>;
+}
+//#endregion
+export { HealthAdapter as n, BaseS3Options as t };

package/dist/v2.d.mts

@@ -0,0 +1,17 @@
+import { n as HealthAdapter, t as BaseS3Options } from "./shared-B3WTV2_N.mjs";
+import AWS from "aws-sdk";
+
+//#region src/v2.d.ts
+type S3V2 = AWS.S3;
+interface S3V2AdapterOptionsWithClient extends BaseS3Options<S3V2> {
+  client: S3V2;
+  config?: never;
+}
+interface S3V2AdapterOptionsWithConfig extends BaseS3Options<S3V2> {
+  config?: AWS.S3.ClientConfiguration;
+  client?: never;
+}
+type S3V2AdapterOptions = S3V2AdapterOptionsWithClient | S3V2AdapterOptionsWithConfig;
+declare function s3V2Adapter(options: S3V2AdapterOptions): HealthAdapter;
+//#endregion
+export { S3V2AdapterOptions, S3V2AdapterOptionsWithClient, S3V2AdapterOptionsWithConfig, s3V2Adapter };

package/dist/v2.mjs

@@ -0,0 +1 @@
+import{n as e,t}from"./shared-B-1hAtzF.mjs";function n(n){let r=null;async function i(){if(`client`in n&&n.client)return n.client;if(!r){let{default:e}=await import(`aws-sdk`);r=new e.S3(n.config??{})}return r}return{async check(){try{let t=await i(),r=Date.now(),a=await new Promise((e,n)=>{t.listBuckets((t,r)=>{t?n(t):e(r)})}),o=Date.now()-r,s=n.metadata?n.metadata(t):void 0,c=s instanceof Promise?await s:s,l=a.Buckets?.length??0;return e(o,{...c,bucketCount:l})}catch(e){return t(e)}}}}export{n as s3V2Adapter};

package/dist/v3.d.mts

@@ -0,0 +1,16 @@
+import { n as HealthAdapter, t as BaseS3Options } from "./shared-B3WTV2_N.mjs";
+import { S3Client, S3ClientConfig } from "@aws-sdk/client-s3";
+
+//#region src/v3.d.ts
+interface S3V3AdapterOptionsWithClient extends BaseS3Options<S3Client> {
+  client: S3Client;
+  config?: never;
+}
+interface S3V3AdapterOptionsWithConfig extends BaseS3Options<S3Client> {
+  config?: S3ClientConfig;
+  client?: never;
+}
+type S3V3AdapterOptions = S3V3AdapterOptionsWithClient | S3V3AdapterOptionsWithConfig;
+declare function s3V3Adapter(options: S3V3AdapterOptions): HealthAdapter;
+//#endregion
+export { S3V3AdapterOptions, S3V3AdapterOptionsWithClient, S3V3AdapterOptionsWithConfig, s3V3Adapter };

package/dist/v3.mjs

@@ -0,0 +1 @@
+import{n as e,t}from"./shared-B-1hAtzF.mjs";function n(n){let r=null;async function i(){if(`client`in n&&n.client)return n.client;if(!r){let{S3Client:e}=await import(`@aws-sdk/client-s3`);r=new e(n.config??{})}return r}return{async check(){try{let t=await i(),r=Date.now(),{ListBucketsCommand:a}=await import(`@aws-sdk/client-s3`),o=await t.send(new a({})),s=Date.now()-r,c=n.metadata?n.metadata(t):void 0,l=c instanceof Promise?await c:c,u=o.Buckets?.length??0;return e(s,{...l,bucketCount:u})}catch(e){return t(e)}}}}export{n as s3V3Adapter};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@healthzkit/s3",
+  "version": "0.0.1",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alasti-company/healthzkit.dev",
+    "directory": "packages/s3"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./v2": "./dist/v2.mjs",
+    "./v3": "./dist/v3.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "prepublishOnly": "vp run build"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1053.0",
+    "@types/node": "^25.6.2",
+    "@typescript/native-preview": "7.0.0-dev.20260509.2",
+    "aws-sdk": "2.1693.0",
+    "bumpp": "^11.1.0",
+    "healthzkit": "workspace:*",
+    "typescript": "^6.0.3",
+    "vite-plus": "^0.1.20"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": ">=3.0.0",
+    "aws-sdk": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "aws-sdk": {
+      "optional": true
+    }
+  }
+}