@ontemper/sdk 0.8.0 → 0.8.2

package/README.md

@@ -325,6 +325,57 @@ approved; another runtime refuses a partner with TLS settings or a proxy. In tes
 `@temper/workflow/as2/testing` and pass its `fetch` to `testPlatform`; it keeps the platform ledger rules and runs
 no crypto.
 
+## PostgreSQL
+
+`@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 { makePostgresqlPool } from '@temper/workflow/resources';
+
+// In an Effect service: the pool ends with the scope, and its password masks the workflow's log lines.
+const Ledger = Layer.effect(LedgerService, Effect.map(makePostgresqlPool('orders-db'), makeLedger));
+```
+
+The pool resolves the Resource through the runtime API and opens no connection until the first query. It
+holds at most 5 connections, with a 10 s connect timeout, a 30 s idle timeout, and a 10 s statement timeout.
+A statement timeout logs `temper.database.query.timeout`, and an idle connection error logs
+`temper.database.connection.error`, without the query or the server text. `sslmode` maps to TLS as libpq does
+(`disable`, `require`, `verify-ca`, `verify-full`; default `verify-full`). A Resource without a password sends an
+empty one, never `PGPASSWORD` or `.pgpass`. A stale password (over 30 s old) is re-read in the background for later
+connections, so a rotated password applies without a restart; a failed re-read keeps the last password and logs
+`temper.database.password.refresh.failed`. Changes to other fields apply at the next restart. A record with an SSH tunnel or RDS IAM authentication fails with
+`InvalidResourceError`.
+
+Deployed workflows and external databases connect over native TCP. In a builder sandbox
+(`TEMPER_DATABASE_TUNNEL=websocket`), a Temper-managed Resource connects through the Resources-authenticated
+WebSocket tunnel. Each physical connection reads the current runtime token, and a refused tunnel fails the
+connection without a TCP fallback.
+
+## Resource records and Kafka
+
+`@temper/workflow/resources` gives Effect workflows the record schemas and Kafka options of `@ontemper/resources`:
+`KafkaResource`, `S3Resource`, `AzureBlobResource`, `SftpResource`, `PostgresqlResource`, and `kafkaConfig`. 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));
+```
+
+A record that a built-in schema rejects fails the read with the field name, never the value. An unknown closed
+value, such as a new `sslmode`, fails with `UnknownRecordValueError`.
+
+This release has no promise-style `env`: no `env.resources`, `env.variables`, `initialize`, or `reload`. Code that
+cannot run an Effect keeps `@ontemper/resources`; this entry does not modify that package. The legacy partners and
+connections APIs are excluded.
+
 ## Versions
 
 CI publishes every version to npm as `@ontemper/sdk`; nobody publishes by hand. Workflow code keeps
@@ -338,9 +389,12 @@ 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 eight entry points: `@temper/workflow`, `@temper/workflow/testing`,
+The package has nine entry points: `@temper/workflow`, `@temper/workflow/testing`,
 `@temper/workflow/contract`, `@temper/workflow/sftp`, `@temper/workflow/sftp/testing`,
-`@temper/workflow/edi`, `@temper/workflow/as2`, and `@temper/workflow/as2/testing`. Only `/sftp` loads `ssh2`. `@temper/workflow/contract` holds the runtime Resources HttpApi and the
+`@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.
 
 ## Develop and release