@ontemper/sdk 0.7.1-postgresql.1 → 0.7.1-postgresql.3

package/README.md

@@ -326,11 +326,11 @@ no crypto.
 
 ## PostgreSQL
 
-`@temper/workflow/postgresql` opens a `pg.Pool` for a PostgreSQL Resource by key. It loads `pg` and `ws`, which
-the workflow installs; no other entry point loads them. TypeScript code also needs `@types/pg`.
+`@temper/workflow/resources` opens a `pg.Pool` for a PostgreSQL Resource by key. A pool loads `pg`, and a builder's
+tunnel to a Temper-managed database loads `ws`, which the workflow installs; importing the entry point loads neither. TypeScript code also needs `@types/pg`.
 
 ```ts
-import { createPostgresqlPool, makePostgresqlPool } from '@temper/workflow/postgresql';
+import { createPostgresqlPool, makePostgresqlPool } from '@temper/workflow/resources';
 
 // A script or a module-level pool; the caller ends it with `pool.end()`.
 const pool = await createPostgresqlPool('orders-db');
@@ -353,6 +353,49 @@ WebSocket tunnel. Each physical connection reads the current runtime token, and
 connection without a TCP fallback. `createPostgresqlPool` registers the password in the process-wide secret
 registry; inside a workflow handler, prefer `makePostgresqlPool`, which registers it in the workflow's own.
 
+## Resource records and Kafka
+
+`@temper/workflow/resources` gives Effect workflows what `@ontemper/resources` gives legacy ones: record schemas
+(`KafkaResource`, `S3Resource`, `AzureBlobResource`, `SftpResource`, `PostgresqlResource`), `kafkaConfig`, and a promise
+`env` for code that cannot run an Effect. Declare the Resource with `Resource` from the root; its secrets arrive as
+`Redacted` values, and `kafkaConfig` unwraps them itself. It loads the optional peers `@aws-sdk/credential-providers` and
+`aws-msk-iam-sasl-signer-js` only for AWS MSK IAM.
+
+```ts
+import { Resource } from '@temper/workflow';
+import { KafkaResource, kafkaConfig } from '@temper/workflow/resources';
+import { Kafka } from 'kafkajs';
+
+class Events extends Resource<Events>()('events', { type: 'kafka', schema: KafkaResource }) {}
+
+// In an Effect: const kafka = new Kafka(kafkaConfig(yield* Events));
+```
+
+For scripts outside Effect, the subpath exports the promise-style `env`:
+
+```ts
+import { env, S3Resource } from '@temper/workflow/resources';
+
+const archive = await env.resources.resolve('archive', S3Resource);
+const metadata = await env.resources.inspect('archive');
+const { key } = await env.resources.select({ resourceTypeKey: 'http_api', match: { tenantKey } });
+const region = await env.variables.get('PARTNER_REGION');
+```
+
+Without a schema, `resolve` returns the JSON object; with one, it decodes it and keeps extension fields.
+`ResourceNotFoundError` means the key or selection has no record. A found record with a missing reference
+fails with `InvalidResourceError`; unknown closed values in a built-in schema fail with `UnknownRecordValueError`.
+Authorization failures use `ResourcesUnauthorizedError`; outages use `ResourcesUnavailableError`.
+
+Promise reads use the same runtime API and Run token as the declarations. Their cache matches the legacy
+resolver: a 30 s TTL, up to 15 min of stale reads through an outage (5 min for selections), and a separate
+10 s select-miss cache with a cap of 60 distinct misses per minute. `{ cache: false }` bypasses it;
+`{ ttlMs }` sets a read's TTL. The legacy cache environment settings still apply.
+
+The runtime API cannot list Variables, so snapshot `initialize`, `reload`, `variables.tryGet`, and
+`variables.has` have no equivalent. The legacy partners and connections APIs are also excluded.
+Existing workflows can keep `@ontemper/resources`; this entry does not modify that package.
+
 ## Versions
 
 CI publishes every version to npm as `@ontemper/sdk`; nobody publishes by hand. Workflow code keeps
@@ -366,10 +409,11 @@ npm install --save-exact @temper/workflow@npm:@ontemper/sdk@<version>
 A published version never changes. The workflow template and the examples pin one exact
 version; `pnpm sdk:pin` moves them all together.
 
-The package has nine entry points: `@temper/workflow`, `@temper/workflow/testing`,
+The package has ten entry points: `@temper/workflow`, `@temper/workflow/testing`,
 `@temper/workflow/contract`, `@temper/workflow/sftp`, `@temper/workflow/sftp/testing`,
-`@temper/workflow/edi`, `@temper/workflow/as2`, `@temper/workflow/as2/testing`, and `@temper/workflow/postgresql`.
-Only `/sftp` loads `ssh2`, and only `/postgresql` loads `pg` and `ws` (optional peer dependencies).
+`@temper/workflow/edi`, `@temper/workflow/as2`, `@temper/workflow/as2/testing`, and `@temper/workflow/resources`.
+Only `/sftp` loads `ssh2`. In `/resources`, only a PostgreSQL pool loads `pg` and `ws`, and only AWS MSK IAM loads
+`@aws-sdk/credential-providers` and `aws-msk-iam-sasl-signer-js` (optional peer dependencies).
 `@temper/workflow/contract` holds the runtime Resources HttpApi and the
 manifest, trigger, and invocation schemas that the platform imports. Workflow code rarely needs it.