@jskit-ai/connectors-catalog 0.1.1

package/patterns/assistant-mcp-oauth/PATTERN.md

@@ -0,0 +1,235 @@
+---
+id: connectors/assistant-mcp-oauth
+title: Assistant MCP OAuth with portable files
+summary: Configure assistant OAuth clients, then compose existing state, encrypted file grants and authorized MCP calls.
+keywords: connectors, amplitude, atlassian, canva, figma, miro, hex, confidence, granola, client metadata, mcp, oauth, assistant, cli, files
+requires: @jskit-ai/connectors-core, @jskit-ai/connectors-catalog
+---
+
+# Assistant MCP OAuth with portable files
+
+## Use when
+
+An assistant host or trusted CLI connects its owner's Amplitude, Atlassian, Canva, Figma, Miro, Hex, Confidence or Granola
+account through OAuth and calls MCP tools under that owner's delegated authority.
+
+## Do not use when
+
+This is not app-user login, production event ingestion or automatic assistant
+attachment. Canva supports its documented metadata client; do not assume every
+provider supports a client without a secret. Use the provider guide to
+distinguish supported OAuth from the provider's other APIs.
+
+## Product decisions
+
+Choose the region, callback owner, requested permissions and allowed tool
+operations. The host owns user authentication, argument validation, approvals
+and tool presentation. A discovered tool is not permission to execute it.
+
+## Framework APIs
+
+For HeyGen, import `heygenProvider` and `registerHeyGenClient` from
+`@jskit-ai/connectors-catalog/server/heygen`. Register the assistant host callback
+once and use OAuth with `openid`, `profile`, `email`. Store credentials through
+Env and compose the existing lifecycle. Verification calls `tools.list`, never
+media generation. Authorize `tools.call` names and arguments explicitly; some
+operations consume credits or delete content. API-key profile/voice operations
+remain separate and cannot use an MCP token. See the HeyGen guide and on-screen
+registration steps; no automatic client registration on Connect is implied.
+
+For Granola, import `granolaProvider` and `registerGranolaClient` from
+`@jskit-ai/connectors-catalog/server/granola`. Use an assistant-owned OAuth
+connection with `openid`, `profile`, `email` and `offline_access`. Register the
+host callback once, store the returned secret and callback through Env, then
+use the common authorization lifecycle. Verification calls `tools.list`.
+`tools.call` requires host authorization for the exact name and arguments.
+Granola's API-key mode uses separate REST operations; its key cannot replace
+MCP OAuth. The same provider definition rejects cross-method operations.
+See the Granola guide for provider setup, current plan limits and the explicit
+registration workflow; no automatic DCR-on-connect or EMA support is implied.
+
+Import `amplitudeProvider` and `registerAmplitudeClient` from
+`@jskit-ai/connectors-catalog/server/amplitude`. Use the existing
+`oauth-connection` pattern's parser, connection service, environment resolver
+and encrypted file store with `providers: [amplitudeProvider]`.
+For Atlassian, import `atlassianProvider` and `registerAtlassianClient` from
+`@jskit-ai/connectors-catalog/server/atlassian`. Register both providers when
+using their configurations in the example file. For Canva, import
+`canvaProvider` from `@jskit-ai/connectors-catalog/server/canva` and
+`createCanvaClientMetadata` from `@jskit-ai/connectors-catalog/shared`.
+For Figma and Miro, use `figmaProvider`/`registerFigmaClient` and
+`miroProvider`/`registerMiroClient` from the corresponding
+`@jskit-ai/connectors-catalog/server/figma` and `/server/miro` exports.
+
+## Example files
+
+`example/integrations.json` is the portable configuration, also edited by the
+UI. For Amplitude/Atlassian, replace the Client ID after explicit setup and
+store the client secret and callback in Env. Their registration helper returns
+a secret to the privileged setup caller; never expose it through status UI.
+Canva instead uses its public metadata URL and a callback reference, with no
+client secret. Its metadata builder appears under Variation points.
+
+```js
+const client = await registerAmplitudeClient({
+  region: "us", clientName: "My assistant", callbackUrl: registeredCallback,
+  scopes: ["mcp:read", "offline_access"]
+});
+// Existing host storage persists client.clientSecret securely.
+// The application writes client.clientId into its registration JSON.
+```
+
+Do this once as an authorized setup operation, not on startup or every consent
+attempt. An interrupted request may already have created a provider client.
+Registration neither creates a provider account nor signs in a user.
+
+The `oauth-connection` pattern opens `beginAuthorization`'s URL and handles
+`completeAuthorization` at the registered callback under the same owner.
+Verification only discovers tools. Afterward, apply the `assistant-mcp`
+pattern's exact tool/argument policy before a call:
+
+```js
+const result = await connections.invoke({
+  context, integrationId: "analytics", operation: "tools.call", signal,
+  input: { name: approvedToolName, arguments: approvedArguments }
+});
+```
+
+`approvedToolName` and `approvedArguments` must come from the host's validated,
+authorized request. Check `result.isError` before claiming success. Do not turn
+returned descriptions or content into new authority. The provider's project
+permissions still apply even when discovery lists a tool.
+
+## Invariants
+
+- Amplitude uses the same region for registration, consent, token grants and MCP.
+- Hex uses the selected standard/EU/HIPAA issuer and its distinct `/mcp` resource.
+- Confidence uses separate Flags/Experiments integration grants and paths, with its common `/mcp` OAuth resource.
+- Atlassian uses its v2 resource and issuer; host code never substitutes v1 grants.
+- PKCE/state attempts and refresh grants use the existing file-store owner.
+- The provider's OAuth resource is included in authorization/code/refresh calls.
+- Client secrets and access/refresh tokens never enter the portable JSON.
+- Canva explicitly uses `tokenEndpointAuthMethod: "none"` and no secret field.
+- Read and optional write consent remain distinct; the host authorizes calls.
+- Disconnect/cancellation does not undo previously accepted provider mutations.
+- An operator CLI can use its trusted process identity; a public route cannot.
+
+## Variation points
+
+Select `eu` for an EU-resident account and register the client at that region's
+endpoint. Add `mcp:write` only for authorized content edits.
+For Atlassian, call `registerAtlassianClient` with `clientName`, `callbackUrl`
+and its product `scopes` (no region). Use the `work` integration in the example,
+request only required product permissions, and authorize site/project arguments.
+The provider targets MCP v2 with a flat tool catalogue; v1 clients/tokens cannot
+be reused. Atlassian's authorization server and MCP resource have distinct
+origins, fixed by the provider. Tool discovery may be empty after reduced consent;
+it does not prove product access.
+
+For Canva, the `design` integration uses a hosted client metadata URL. Build its
+public document from the same registration and integration values:
+
+```js
+const registration = configuration.registrations.canva;
+const document = createCanvaClientMetadata({
+  clientId: registration.clientId,
+  clientName: configuration.integrations.design.displayName,
+  callbackUrl: await resolveReference(registration.callbackUrlRef)
+});
+```
+
+Serve `document` as JSON at exactly `registration.clientId` through the host's
+existing static response. The helper does not deploy or publish anything.
+Canva must approve the callback URL; the provider guide gives the application
+steps. Each owner completes consent. Use `design` as the integration ID in
+connection calls, and validate tool arguments against that owner's content.
+Canva's advertised scope list has no `offline_access`; do not add an invented
+permission. The current provider gives MCP operations a 60-second request budget.
+
+For Figma, the `figma-design` example uses its remote server. Obtain Figma client
+approval first, then call `registerFigmaClient({ clientName, callbackUrl })`.
+The helper requests `mcp:connect`; this broad permission can expose write tools.
+Validate file/node arguments and approve the specific call independently.
+Figma's callback includes its issuer; keep that parameter for completion.
+Desktop MCP and REST personal tokens use different mechanisms and are outside
+this fragment.
+
+For Miro, use `miro-boards` and call
+`registerMiroClient({ clientName, callbackUrl, scopes: ["boards:read"] })`.
+Consent selects a team. Reconnect deliberately to change it; do not derive team
+authority from a user-supplied board argument. Add `boards:write` only when
+needed and keep exact tool/argument policy in the host. Identity scopes are
+optional and do not implement app login. Neither Figma nor Miro advertises an
+`offline_access` scope in the metadata used by these fragments.
+
+For providers advertising it, omitting `offline_access` can require renewed consent when access expires.
+The application chooses the callback route and file state directory through its existing owners.
+
+## Verification
+
+Provider tests use simulated OAuth/MCP replies and real encrypted temporary
+files. They verify regional/issuer destinations, setup metadata, permissions,
+restart, refresh, isolation and failures. The editor test proves configuration persistence. No
+sample app is generated or live account/tool operation performed.
+
+## Avoid
+
+Do not register a fresh client on every launch, log the setup result, expose the
+client secret to the browser, or infer permission from a tool's presence in
+discovery. Keep provider content out of the host's authority decisions.
+
+## Hex assistant tools
+
+Use `hexProvider` and `registerHexClient` from
+`@jskit-ai/connectors-catalog/server/hex`. The guide at `docs/hex.md` supplies
+manual setup, a complete portable configuration and managed-host boundaries.
+Set `settings.endpoint` to `standard`, `eu` or `hipaa`; the same value must be
+used during explicit client registration. Single-tenant Hex URLs need separate
+endpoint support. Never redirect existing credentials to a user-supplied URL.
+
+```js
+const client = await registerHexClient({
+  endpoint: "eu", clientName: "My assistant", callbackUrl: registeredCallback,
+  scopes: ["openid", "profile", "email", "offline_access"]
+});
+```
+
+Persist this privileged result through the host's secret/configuration owners,
+then use the common begin/complete OAuth flow. API tokens cannot substitute for
+MCP consent. Identity scopes do not limit tools to reads; authorize each tool
+and argument before calling it. Discover current argument schemas rather than
+inventing `create_thread` or `continue_thread` inputs. Calls can start analysis
+and consume provider credits. Check `isError`, expose progress, and schedule
+bounded follow-up reads explicitly; never replay a Thread creation because a
+response was lost. This fragment does not install tools into an AI automatically
+or use an ID token as an application login session.
+
+## Confidence Flags and Experiments
+
+Import `confidenceFlagsProvider` from
+`@jskit-ai/connectors-catalog/server/confidence-flags` or
+`confidenceExpProvider` from `/server/confidence-exp`. Both export the explicit
+`registerConfidenceClient` setup helper. The individual `docs/confidence-*.md`
+guides supply portable configurations and link to shared registration steps.
+Register the provider(s) with the same connection service and encrypted file store.
+
+```js
+const client = await registerConfidenceClient({
+  clientName: "My assistant", callbackUrl: registeredCallback,
+  scopes: ["openid", "profile", "email", "offline_access"]
+});
+```
+
+Registration is privileged and must not run on every connection. Keep separate
+integration IDs for Flags and Experiments even when they share a client. Their
+OAuth resource is common; that does not authorize another integration's grant.
+The pinned transport must not follow the provider's HTTP discovery challenge.
+The conflicting `flags:read` metadata is documented, not presented as a proven
+permission choice. Identity scopes do not establish read-only tool access.
+
+Use discovery schemas and host policy for each exact tool and resource name.
+Flag management tools can mutate targeting and variants; approve their concrete
+inputs before execution and never replay after a lost response. Experiment
+results can carry summaries or detailed data; preserve errors and let the host
+select the desired view. Neither connector installs an OpenFeature evaluator,
+collects events, provisions a warehouse or automatically attaches tools to an AI.

package/patterns/assistant-mcp-oauth/example/integrations.json

@@ -0,0 +1,102 @@
+{
+  "schemaVersion": 1,
+  "registrations": {
+    "amplitude": {
+      "source": "own",
+      "clientId": "assigned-client-id",
+      "clientSecretRef": "env:AMPLITUDE_CLIENT_SECRET",
+      "callbackUrlRef": "env:AMPLITUDE_CALLBACK_URL"
+    },
+    "atlassian": {
+      "source": "own",
+      "clientId": "assigned-v2-client-id",
+      "clientSecretRef": "env:ATLASSIAN_CLIENT_SECRET",
+      "callbackUrlRef": "env:ATLASSIAN_CALLBACK_URL"
+    },
+    "canva": {
+      "source": "own",
+      "clientId": "https://assistant.example/oauth/canva.json",
+      "tokenEndpointAuthMethod": "none",
+      "callbackUrlRef": "env:CANVA_CALLBACK_URL"
+    },
+    "figma": {
+      "source": "own",
+      "clientId": "assigned-client-id",
+      "clientSecretRef": "env:FIGMA_CLIENT_SECRET",
+      "callbackUrlRef": "env:FIGMA_CALLBACK_URL"
+    },
+    "miro": {
+      "source": "own",
+      "clientId": "assigned-client-id",
+      "clientSecretRef": "env:MIRO_CLIENT_SECRET",
+      "callbackUrlRef": "env:MIRO_CALLBACK_URL"
+    }
+  },
+  "integrations": {
+    "analytics": {
+      "provider": "amplitude",
+      "accountMode": "assistant",
+      "scopes": [
+        "mcp:read",
+        "offline_access"
+      ],
+      "authentication": {
+        "method": "oauth2",
+        "registrationRef": "amplitude"
+      },
+      "settings": {
+        "region": "us"
+      }
+    },
+    "work": {
+      "provider": "atlassian",
+      "accountMode": "assistant",
+      "scopes": [
+        "read:me",
+        "read:jira:agent-interface",
+        "offline_access"
+      ],
+      "authentication": {
+        "method": "oauth2",
+        "registrationRef": "atlassian"
+      }
+    },
+    "design": {
+      "provider": "canva",
+      "displayName": "Design assistant",
+      "accountMode": "assistant",
+      "scopes": [
+        "profile:read",
+        "design:meta:read",
+        "design:content:read",
+        "folder:read"
+      ],
+      "authentication": {
+        "method": "oauth2",
+        "registrationRef": "canva"
+      }
+    },
+    "figma-design": {
+      "provider": "figma",
+      "accountMode": "assistant",
+      "scopes": [
+        "mcp:connect"
+      ],
+      "authentication": {
+        "method": "oauth2",
+        "registrationRef": "figma"
+      }
+    },
+    "miro-boards": {
+      "provider": "miro",
+      "accountMode": "assistant",
+      "scopes": [
+        "boards:read"
+      ],
+      "authentication": {
+        "method": "oauth2",
+        "registrationRef": "miro"
+      }
+    }
+  }
+}

package/patterns/aws-storage-queries/PATTERN.md

@@ -0,0 +1,169 @@
+---
+id: connectors/aws-storage-queries
+title: AWS object storage and Athena queries with explicit credentials
+summary: Compose signed AWS operations, file configuration and application authorization from CLI or server code.
+keywords: aws, s3, athena, iam, sts, connectors, storage, queries, cli, files
+requires: @jskit-ai/connectors-core, @jskit-ai/connectors-catalog
+---
+
+# AWS object storage and Athena queries with explicit credentials
+
+## Use when
+
+An application or an explicitly authorized CLI operator needs objects in one
+S3 bucket, or SQL queries in one Athena workgroup. The package provides the
+runtime: schema validation, SDK signing and response parsing, fixed regional
+origins, file connection storage and operation authorization. AI code only
+composes those libraries with the application's identity and resource policy.
+
+## Do not use when
+
+Do not use this as an application login, an AWS account creator, a general SDK
+proxy, or proof that a managed Vibe64 allocation exists. Do not use a machine's
+default AWS credentials for arbitrary application users. Per-user federation,
+AWS IAM Identity Center, noncommercial AWS partitions and arbitrary endpoints
+are outside the fragment. Athena statements can write data and incur costs;
+connecting does not approve arbitrary future SQL.
+
+## Product decisions
+
+Use the exact [S3](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/connectors-catalog/docs/aws-s3.md) or
+[Athena](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/connectors-catalog/docs/aws-athena.md) JSON. The same file is usable by CLI and the
+Vibe64 form. Store the actual secret access key, access key ID and optional
+session token outside source. The access key ID uses `settings.accessKeyIdRef`,
+the secret uses `authentication.secretRef`, and temporary credentials add
+`settings.sessionTokenRef`. A missing explicit binding is an error.
+
+## Invariants
+
+The host resolver must supply a consistent credential set and renew temporary
+STS credentials. It must not give a public application the paid account's
+identity just because that application names a binding. Resource provisioning,
+account assignments, quotas and credential renewal are separate operations.
+There is no OAuth callback for these modes. See
+[AWS ownership](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/connectors-catalog/docs/aws-credentials.md).
+
+## Framework APIs
+
+Follow the [API-key connection pattern](../api-key-connection/PATTERN.md) to
+read configuration, construct encrypted file storage and define authorization.
+Register the provider exports needed by that application:
+
+```js
+import { awsS3Provider } from "@jskit-ai/connectors-catalog/server/aws-s3";
+import { awsAthenaProvider } from "@jskit-ai/connectors-catalog/server/aws-athena";
+
+const providers = [awsS3Provider, awsAthenaProvider];
+// Pass providers, validated configuration, store, resolveReference and authorize
+// to createConnectionService, or compose the ordinary connector Feature.
+```
+
+Call `service.connectApiKey({context, integrationId})` explicitly. S3 checks a
+ListObjectsV2 page; Athena checks workgroup metadata. Those reads are useful
+verification, not a claim of every object/table permission. API-key
+`grantedScopes` is empty; configured S3 read/write selections only limit local
+operations. IAM and bucket policies still decide access.
+
+## Example files
+
+[example/integrations.json](example/integrations.json) contains both resource slots.
+The [transfer module](example/s3-transfer.js) composes signed GET/PUT with native
+Fetch. Optional [format composition](example/formats/data-formats.js) uses ordinary
+JSON, CSV and Parquet libraries. Its own package manifest, lockfile and focused
+verification command make those optional application dependencies explicit; they
+are not installed for every connector consumer. See the S3 guide for composition.
+Keep the resource slots in `integrations.json` and these calls in an application-owned server module or CLI command.
+
+For S3, authorize the requested prefix/key against the authenticated user before
+invocation. A shared connection does not make the whole bucket public.
+
+```js
+const page = await service.invoke({
+  context, integrationId: "files", operation: "objects.list",
+  input: { prefix: allowedPrefix, maxKeys: 100 }
+});
+const objects = (page.Contents || []).map((object) => ({
+  ...object,
+  Key: page.EncodingType === "url" ? decodeURIComponent(object.Key) : object.Key
+}));
+// NextContinuationToken is opaque: pass it unchanged to the next list call.
+// Authorize the selected decoded key through the same policy before signing.
+const download = await service.invoke({
+  context, integrationId: "files", operation: "objects.downloadUrl",
+  input: { key: authorizedKey, expiresInSeconds: 300 }
+});
+```
+
+`objects.uploadUrl` uses the same key/expiry input and requires configured
+`write`. The result's URL is a temporary bearer credential; return it only to the
+intended caller, without logging it. Transfer with its exact GET/PUT method and
+URL. A PUT body can overwrite that object. Neither signing nor a successful
+connection proves delivery. Keys preserve spaces and literal percent signs;
+never normalize paths. Standalone `.`/`..` segments are intentionally rejected.
+Browser transfers need appropriate bucket CORS for the current app origin.
+
+For Athena discovery, invoke `catalogs.list` (optional `maxResults` 2–50 and
+`nextToken`), `databases.list` (`catalog`, optional page fields), then
+`tables.list` (`catalog`, `database`, optional page fields). Database/table pages
+allow 1–50 rows. Preserve returned column and partition types and pass each
+opaque `NextToken` unchanged. Workgroup selection is not catalog isolation:
+authorize the catalog/database and exposed metadata for the current caller.
+These operations require the Athena/Glue permissions listed in the provider
+guide and do not execute SQL or provision a catalog.
+
+For Athena, construct or select the exact authorized statement, database and
+catalog on the server. Do not expose an unrestricted `query.start` proxy to
+untrusted users. Bind its logical request token and returned query ID to the
+application owner in the application's own state (files are sufficient).
+
+```js
+const started = await service.invoke({
+  context, integrationId: "queries", operation: "query.start",
+  input: { sql: authorizedSql, clientRequestToken: logicalRequestToken,
+    database: authorizedDatabase }
+});
+const status = await service.invoke({
+  context, integrationId: "queries", operation: "query.status",
+  input: { queryId: started.QueryExecutionId }
+});
+```
+
+The token is 32–128 characters and must identify one authorized logical query.
+Reuse it with identical input after an ambiguous start response; the adapter
+never replays automatically. A returned query ID is not completion. When status
+is SUCCEEDED, request `query.results` with that authorized ID and a bounded page
+size. Preserve column types, header rows, empty cells and string values. Pass
+`NextToken` unchanged to retrieve another page.
+
+For cancellation, call `query.cancel` with an authorized query ID; then inspect
+status when final cancellation must be known. Aborting a local HTTP request,
+closing the UI or disconnecting does not cancel an AWS query. Before status,
+results or cancellation, the library checks the execution's workgroup. The
+application must still enforce ownership within that workgroup.
+
+## Variation points
+
+Choose long-lived IAM-user bindings or host-renewed STS bindings. Add S3 write
+only when the application supports uploads. Result storage can be supplied by
+the Athena workgroup or configured in the file; the workgroup can enforce its
+own location. These choices use the same runtime APIs.
+
+## Avoid
+
+Do not expose presigned URLs in logs, infer table permission from a workgroup
+read, treat workgroup membership as user isolation, or poll queries without an
+application-controlled limit.
+
+## Verification
+
+Missing credential references fail before HTTP. Expired/rejected AWS credentials
+require renewal and reconnection. Region changes require verification again.
+Permission failures and account throttling are distinct, redacted errors.
+Signing and SDK requests respect the core timeout/cancellation signal and use
+one attempt with no redirects. Never respond to an IAM denial by switching to
+another account or broadening a policy automatically.
+
+Use the focused `packages/connectors-catalog/test/aws.test.js` for protocol and
+file-persistence proof. Public editor tests cover portable fields and reload;
+shared-form checks cover responsive composition. No live AWS account, actual
+object transfer, SQL execution or generated app is needed for this test scope.

package/patterns/aws-storage-queries/example/formats/data-formats.js

@@ -0,0 +1,35 @@
+import { parse } from "csv-parse/sync";
+import { stringify } from "csv-stringify/sync";
+import { parquetReadObjects } from "hyparquet";
+import { parquetWriteBuffer } from "hyparquet-writer";
+
+// Application-owned, in-memory composition for bounded files. The format is an
+// explicit application decision, never guessed from an untrusted filename.
+export function encodeDataFile(format, value) {
+  if (format === "json") {
+    const text = JSON.stringify(value);
+    if (text === undefined) throw new TypeError("Supply a JSON-serializable value.");
+    return new TextEncoder().encode(text);
+  }
+  // CSV is an array of row arrays, including any header row. Preserve strings
+  // rather than guessing numeric types or discarding leading zeroes.
+  if (format === "csv") return new TextEncoder().encode(stringify(value));
+  // Parquet requires native columnData: [{ name, type, data }]. The application
+  // supplies its explicit schema; do not infer a schema from an empty table.
+  if (format === "parquet") return new Uint8Array(parquetWriteBuffer({ columnData: value }));
+  throw new TypeError("Choose json, csv or parquet.");
+}
+
+export async function decodeDataFile(format, bytes, { maxBytes = 8 * 1024 * 1024 } = {}) {
+  if (!(bytes instanceof Uint8Array)) throw new TypeError("Supply file bytes as Uint8Array.");
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || bytes.byteLength > maxBytes) {
+    throw new RangeError("File exceeds the application's in-memory parsing limit.");
+  }
+  if (format === "parquet") return parquetReadObjects({
+    file: bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength)
+  });
+  const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  if (format === "json") return JSON.parse(text);
+  if (format === "csv") return parse(text, { bom: true });
+  throw new TypeError("Choose json, csv or parquet.");
+}

package/patterns/aws-storage-queries/example/formats/package-lock.json

@@ -0,0 +1,49 @@
+{
+  "name": "s3-native-format-example",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "s3-native-format-example",
+      "dependencies": {
+        "csv-parse": "7.0.2",
+        "csv-stringify": "6.8.3",
+        "hyparquet": "1.30.1",
+        "hyparquet-writer": "0.16.9"
+      }
+    },
+    "node_modules/csv-parse": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/csv-parse/-/csv-parse-7.0.2.tgz",
+      "integrity": "sha512-uKZghv9UmPkMVLYy//KZ9HFAIJsl7wkhoEdIL0+rhuSY9pZQlhaeGEDPIe+/w7eh81MOql8Q/9+inAGWG6ZHYA==",
+      "license": "MIT"
+    },
+    "node_modules/csv-stringify": {
+      "version": "6.8.3",
+      "resolved": "https://registry.npmjs.org/csv-stringify/-/csv-stringify-6.8.3.tgz",
+      "integrity": "sha512-gIeSCvq5F4VtXV3naV3VAewLhBkiZBz+PPhTOA8H3Y8h/ELa+R1ml0GZck/4/Nzo9ep2lvOluilJ6MJlbZsKMA==",
+      "license": "MIT"
+    },
+    "node_modules/hyparquet": {
+      "version": "1.30.1",
+      "resolved": "https://registry.npmjs.org/hyparquet/-/hyparquet-1.30.1.tgz",
+      "integrity": "sha512-307mnGbxzx0nXPGTV6Mhp10gKIu6t+NhvBQJF+PVQsHA295sqznlVOqEAH+fohH2Rqx7NV0Myh9rmuM9E9Ch+w==",
+      "license": "MIT"
+    },
+    "node_modules/hyparquet-writer": {
+      "version": "0.16.9",
+      "resolved": "https://registry.npmjs.org/hyparquet-writer/-/hyparquet-writer-0.16.9.tgz",
+      "integrity": "sha512-VZvH4Vq9lQwZa/+1y4YrEwF9+FAe5pED+mVN4AHflCoFk5LG2RemMHW9iwVlVqug7fO3ATwEMSG68cr3uZAkjQ==",
+      "license": "MIT",
+      "dependencies": {
+        "hyparquet": "1.29.2"
+      }
+    },
+    "node_modules/hyparquet-writer/node_modules/hyparquet": {
+      "version": "1.29.2",
+      "resolved": "https://registry.npmjs.org/hyparquet/-/hyparquet-1.29.2.tgz",
+      "integrity": "sha512-2LxinZ8X0JqToST+9OXcy9t3t5Q7ZneMTkSqUx/36Hv18pCTk/N71IWZc7APTSNG1Me39l/jjEvzZSZ0R+Knbw==",
+      "license": "MIT"
+    }
+  }
+}

package/patterns/aws-storage-queries/example/formats/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "s3-native-format-example",
+  "private": true,
+  "type": "module",
+  "scripts": { "test": "node --test --test-concurrency=1 verify-formats.mjs" },
+  "dependencies": {
+    "csv-parse": "7.0.2",
+    "csv-stringify": "6.8.3",
+    "hyparquet": "1.30.1",
+    "hyparquet-writer": "0.16.9"
+  }
+}

package/patterns/aws-storage-queries/example/formats/verify-formats.mjs

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { encodeDataFile, decodeDataFile } from "./data-formats.js";
+
+test("JSON retains structured values and rejects malformed content", async () => {
+  const value = { name: "Málaga", enabled: true, count: 2, values: [null, "001"] };
+  assert.deepEqual(await decodeDataFile("json", encodeDataFile("json", value)), value);
+  await assert.rejects(decodeDataFile("json", new TextEncoder().encode('{"bad":')), SyntaxError);
+});
+
+test("CSV retains quoted commas, quotes, newlines, empty cells and leading zeroes", async () => {
+  const rows = [["id", "description"], ["001", 'comma, quote " and\nnewline'], ["002", ""]];
+  assert.deepEqual(await decodeDataFile("csv", encodeDataFile("csv", rows)), rows);
+  await assert.rejects(decodeDataFile("csv", new TextEncoder().encode('"unterminated')), /Quote Not Closed/);
+});
+
+test("Parquet creates an actual file and reads explicit typed nullable columns", async () => {
+  const encoded = encodeDataFile("parquet", [
+    { name: "name", type: "STRING", data: ["Málaga", "Sydney"] },
+    { name: "count", type: "INT32", data: [3, null] },
+    { name: "active", type: "BOOLEAN", data: [true, false] }
+  ]);
+  assert.equal(new TextDecoder().decode(encoded.slice(0, 4)), "PAR1");
+  const padded = new Uint8Array(encoded.length + 6);
+  padded.set(encoded, 3);
+  assert.deepEqual(await decodeDataFile("parquet", padded.subarray(3, -3)), [
+    { name: "Málaga", count: 3, active: true }, { name: "Sydney", count: null, active: false }
+  ]);
+  await assert.rejects(decodeDataFile("parquet", encoded.slice(0, 12)));
+});
+
+test("native composition rejects invalid UTF-8, excess bytes and unknown formats", async () => {
+  await assert.rejects(decodeDataFile("csv", new Uint8Array([255])), TypeError);
+  await assert.rejects(decodeDataFile("json", new Uint8Array(9), { maxBytes: 8 }), RangeError);
+  await assert.rejects(decodeDataFile("xml", new Uint8Array()), TypeError);
+  assert.throws(() => encodeDataFile("xml", []), TypeError);
+});