@vyriy/services 0.2.0 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,65 @@
+# Vyriy Package Agent Guide
+
+This package belongs to the Vyriy toolkit. Keep changes calm, explicit, reusable, and easy to reason about.
+
+## Architecture
+
+- Prefer simple modules over clever frameworks or hidden conventions.
+- Keep package boundaries explicit and avoid project-specific coupling.
+- Extract only proven reusable behavior.
+- Keep public APIs small, typed, documented, and stable.
+- Prefer SSR-friendly and SSG-friendly code paths.
+- Keep integrations replaceable and avoid hard coupling to a CMS or runtime host.
+- Prefer AWS serverless-compatible assumptions when infrastructure concerns appear.
+
+## File Shape
+
+- Prefer one exported runtime method, component, or helper per production file when it stays readable.
+- Prefer one matching test file per production file, for example `feature.ts` and `feature.test.ts`.
+- Use focused folders when behavior naturally splits into several related files.
+- Keep `index.ts` as a public re-export surface only. Do not place implementation logic in it.
+- Use `.js` relative import and export specifiers in TypeScript source where package style requires it.
+- Add `types.ts` when public shared types are part of the package contract.
+- Keep constants near the code that owns them unless they are shared or clarify repeated behavior.
+
+## Public Surface
+
+- Every new public export should be re-exported from `index.ts`.
+- Add or update `index.test.ts` when the public export surface changes.
+- Add JSDoc for public exports when behavior, parameters, return values, or usage expectations need explanation.
+- Do not hand-maintain source package `exports` maps unless the package has a real custom publishing need.
+
+## Tests
+
+- Tests use Jest and `@jest/globals`.
+- Cover public behavior and meaningful edge cases.
+- Prefer behavior-focused tests over private implementation lock-in.
+- When mocking modules, install mocks before loading the module under test.
+- Use focused validation when changing package behavior:
+
+```bash
+yarn jest packages/<package> --runInBand --coverage=false
+```
+
+## Documentation
+
+- Keep `README.md` concise and usage-oriented.
+- Start package READMEs with `# @vyriy/<package>`.
+- Document real public exports, supported options, and examples that actually work.
+- Keep `doc.mdx` as the Storybook/docs wrapper for the README when the package participates in docs.
+- For component packages, include Storybook coverage for supported states and common usage.
+
+## Components
+
+- Prefer lightweight React 19+ components with TypeScript.
+- Keep components SSR-friendly and avoid browser globals during render.
+- Prefer composable props and Bootstrap-compatible ergonomics where practical.
+- Put each public component in its own file with a matching test.
+- Add Storybook stories when a component has visual states, variants, or interaction states.
+
+## Change Discipline
+
+- Keep changes scoped to the requested behavior.
+- Avoid unrelated refactors and metadata churn.
+- Sync implementation, tests, README, `doc.mdx`, and public re-exports together.
+- Prefer the option that is simpler to explain, easier to evolve, and calmer to maintain.

package/README.md

@@ -46,6 +46,9 @@ Some clients are prepared for local AWS-compatible development:
 - `cloudfront`, `lambda`, `sns`, and `ssm` currently use their normal AWS SDK
   client configuration.
 
+Service clients are created lazily inside each helper call. Importing
+`@vyriy/services` or a service subpath does not construct AWS SDK clients.
+
 LocalStack defaults come from `@vyriy/env`:
 
 - `LOCALSTACK_HOST`: defaults to `localhost`
@@ -73,6 +76,16 @@ const apiUrl = await getParameter('/app/api-url');
 await upload('assets-bucket', 'config/api-url.txt', apiUrl, 'text/plain');
 ```
 
+Client factories are also exported from service subpaths when direct AWS SDK
+access is needed. The service path gives the generic `createClient` name its
+context:
+
+```ts
+import { createClient } from '@vyriy/services/s3';
+
+const client = createClient({ region: 'eu-central-1' });
+```
+
 ## Examples
 
 Invalidate CloudFront after publishing static files:

package/cloudfront/actions.js

@@ -2,9 +2,10 @@ import { CreateInvalidationCommand, GetInvalidationCommand } from '@aws-sdk/clie
 import { createLogger } from '@vyriy/logger';
 import { pause } from '@vyriy/pause';
 import { toError } from '@vyriy/error';
-import { client } from './client.js';
+import { createClient } from './client.js';
 export const invalidate = async (distribution, paths, shouldWait = false) => {
     try {
+        const client = createClient();
         const logger = createLogger();
         logger.info('Distribution:', distribution);
         logger.info('Paths:', paths);

package/cloudfront/client.d.ts

@@ -1,2 +1,2 @@
-import { CloudFrontClient } from '@aws-sdk/client-cloudfront';
-export declare const client: CloudFrontClient;
+import { CloudFrontClient, type CloudFrontClientConfig } from '@aws-sdk/client-cloudfront';
+export declare const createClient: (options?: CloudFrontClientConfig) => CloudFrontClient;

package/cloudfront/client.js

@@ -1,2 +1,2 @@
 import { CloudFrontClient } from '@aws-sdk/client-cloudfront';
-export const client = new CloudFrontClient({});
+export const createClient = (options = {}) => new CloudFrontClient(options);

package/dynamodb/actions.js

@@ -2,9 +2,10 @@ import { CreateTableCommand } from '@aws-sdk/client-dynamodb';
 import { DeleteCommand, GetCommand, PutCommand, QueryCommand, ScanCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
 import { createLogger } from '@vyriy/logger';
 import { toError } from '@vyriy/error';
-import { client } from './client.js';
+import { createClient } from './client.js';
 export const createTable = async (params) => {
     try {
+        const client = createClient();
         createLogger().log('CreateTableCommand:', params);
         await client.send(new CreateTableCommand(params));
     }
@@ -14,6 +15,7 @@ export const createTable = async (params) => {
 };
 export const createItem = async (TableName, Item, options = {}) => {
     try {
+        const client = createClient();
         createLogger().log('PutCommand:', { TableName, Item, ...options });
         await client.send(new PutCommand({ TableName, Item, ...options }));
     }
@@ -23,6 +25,7 @@ export const createItem = async (TableName, Item, options = {}) => {
 };
 export const updateItem = async (TableName, Key, UpdateExpression, ExpressionAttributeValues, options = {}) => {
     try {
+        const client = createClient();
         const logger = createLogger();
         const params = {
             TableName,
@@ -40,6 +43,7 @@ export const updateItem = async (TableName, Key, UpdateExpression, ExpressionAtt
 };
 export const getItem = async (TableName, Key, options = {}) => {
     try {
+        const client = createClient();
         createLogger().log('GetCommand:', { TableName, Key, ...options });
         return await client.send(new GetCommand({ TableName, Key, ...options })).then(({ Item }) => Item);
     }
@@ -49,6 +53,7 @@ export const getItem = async (TableName, Key, options = {}) => {
 };
 export const deleteItem = async (TableName, Key, options = {}) => {
     try {
+        const client = createClient();
         createLogger().log('DeleteCommand:', { TableName, Key, ...options });
         await client.send(new DeleteCommand({ TableName, Key, ...options }));
     }
@@ -58,6 +63,7 @@ export const deleteItem = async (TableName, Key, options = {}) => {
 };
 export const getItems = async (TableName, keys, options = {}) => {
     try {
+        const client = createClient();
         const logger = createLogger();
         const expressionList = [];
         const ExpressionAttributeNames = {};
@@ -93,6 +99,7 @@ export const getItems = async (TableName, keys, options = {}) => {
 };
 export const getAllItems = async (TableName, options = {}) => {
     try {
+        const client = createClient();
         const logger = createLogger();
         const params = { TableName, ...options };
         const items = [];
@@ -113,6 +120,7 @@ export const getAllItems = async (TableName, options = {}) => {
 };
 export const getAllItemsWithHandler = async (TableName, handler, options = {}) => {
     try {
+        const client = createClient();
         const logger = createLogger();
         const params = { TableName, ...options };
         const scanUntilDone = async (ExclusiveStartKey) => {

package/dynamodb/client.d.ts

@@ -1,2 +1,2 @@
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-export declare const client: DynamoDBClient;
+import { DynamoDBClient, type DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+export declare const createClient: (options?: DynamoDBClientConfig) => DynamoDBClient;

package/dynamodb/client.js

@@ -1,9 +1,11 @@
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { getLocalstackHost, getLocalstackPort, getRegion, isLocal } from '@vyriy/env';
-const options = isLocal()
-    ? {
-        region: getRegion(),
-        endpoint: `http://${getLocalstackHost()}:${getLocalstackPort()}`,
-    }
-    : {};
-export const client = new DynamoDBClient(options);
+export const createClient = (options = {}) => {
+    const defaultOptions = isLocal()
+        ? {
+            region: getRegion(),
+            endpoint: `http://${getLocalstackHost()}:${getLocalstackPort()}`,
+        }
+        : {};
+    return new DynamoDBClient({ ...defaultOptions, ...options });
+};

package/ecs/actions.js

@@ -1,7 +1,7 @@
 import { RunTaskCommand } from '@aws-sdk/client-ecs';
 import { getEcsClusterName, getEcsTaskDefinition, getVpcSecurityGroup, getVpcSubnets } from '@vyriy/env';
 import { createLogger } from '@vyriy/logger';
-import { client } from './client.js';
+import { createClient } from './client.js';
 export const runTask = async (task, environment = [], taskDefinition = getEcsTaskDefinition()) => {
     const cluster = getEcsClusterName();
     const subnets = getVpcSubnets();
@@ -46,5 +46,6 @@ export const runTask = async (task, environment = [], taskDefinition = getEcsTas
         },
     };
     createLogger().info('Params:', params);
+    const client = createClient();
     await client.send(new RunTaskCommand(params));
 };

package/ecs/client.d.ts

@@ -1,2 +1,2 @@
-import { ECSClient } from '@aws-sdk/client-ecs';
-export declare const client: ECSClient;
+import { ECSClient, type ECSClientConfig } from '@aws-sdk/client-ecs';
+export declare const createClient: (options?: ECSClientConfig) => ECSClient;

package/ecs/client.js

@@ -1,4 +1,6 @@
 import { ECSClient } from '@aws-sdk/client-ecs';
 import { getRegion, isLocal } from '@vyriy/env';
-const options = isLocal() ? { region: getRegion() } : {};
-export const client = new ECSClient(options);
+export const createClient = (options = {}) => {
+    const defaultOptions = isLocal() ? { region: getRegion() } : {};
+    return new ECSClient({ ...defaultOptions, ...options });
+};

package/lambda/actions.js

@@ -1,7 +1,8 @@
 import { InvokeCommand } from '@aws-sdk/client-lambda';
 import { createLogger } from '@vyriy/logger';
-import { client } from './client.js';
+import { createClient } from './client.js';
 export const invoke = async (functionName, payload, options = {}) => {
+    const client = createClient();
     const logger = createLogger();
     logger.info('functionName:', functionName);
     logger.info('payload:', payload);

package/lambda/client.d.ts

@@ -1,2 +1,2 @@
-import { LambdaClient } from '@aws-sdk/client-lambda';
-export declare const client: LambdaClient;
+import { LambdaClient, type LambdaClientConfig } from '@aws-sdk/client-lambda';
+export declare const createClient: (options?: LambdaClientConfig) => LambdaClient;

package/lambda/client.js

@@ -1,4 +1,6 @@
 import { LambdaClient } from '@aws-sdk/client-lambda';
 import { getRegion } from '@vyriy/env';
-const options = { region: getRegion() };
-export const client = new LambdaClient(options);
+export const createClient = (options = {}) => {
+    const defaultOptions = { region: getRegion() };
+    return new LambdaClient({ ...defaultOptions, ...options });
+};

package/package.json

@@ -1,24 +1,25 @@
 {
   "name": "@vyriy/services",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared services package for Vyriy projects",
   "type": "module",
   "main": "./index.js",
   "dependencies": {
-    "@aws-sdk/client-cloudfront": "^3.1045.0",
-    "@aws-sdk/client-dynamodb": "^3.1045.0",
-    "@aws-sdk/client-ecs": "^3.1045.0",
-    "@aws-sdk/client-lambda": "^3.1045.0",
-    "@aws-sdk/client-s3": "^3.1045.0",
-    "@aws-sdk/client-sns": "^3.1045.0",
-    "@aws-sdk/client-ssm": "^3.1045.0",
-    "@aws-sdk/lib-dynamodb": "^3.1045.0",
+    "@aws-sdk/client-cloudfront": "^3.1046.0",
+    "@aws-sdk/client-dynamodb": "^3.1046.0",
+    "@aws-sdk/client-ecs": "^3.1046.0",
+    "@aws-sdk/client-lambda": "^3.1046.0",
+    "@aws-sdk/client-s3": "^3.1046.0",
+    "@aws-sdk/client-sns": "^3.1046.0",
+    "@aws-sdk/client-ssm": "^3.1046.0",
+    "@aws-sdk/lib-dynamodb": "^3.1046.0",
     "@aws-sdk/util-dynamodb": "^3.996.2",
-    "@vyriy/env": "0.2.0",
-    "@vyriy/error": "0.2.0",
-    "@vyriy/logger": "0.2.0",
-    "@vyriy/pause": "0.2.0"
+    "@vyriy/env": "0.3.0",
+    "@vyriy/error": "0.3.0",
+    "@vyriy/logger": "0.3.0",
+    "@vyriy/pause": "0.3.0"
   },
+  "agents": "./AGENTS.md",
   "license": "MIT",
   "repository": {
     "type": "git",

package/s3/actions.js

@@ -1,9 +1,10 @@
 import { GetObjectCommand, HeadObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3';
 import { createLogger } from '@vyriy/logger';
 import { toError } from '@vyriy/error';
-import { client } from './client.js';
+import { createClient } from './client.js';
 export const download = async (bucketName, path, options = {}) => {
     try {
+        const client = createClient();
         const logger = createLogger();
         logger.log('GetObjectCommand:', { Bucket: bucketName, Key: path, ...options });
         const response = await client.send(new GetObjectCommand({ Bucket: bucketName, Key: path, ...options }));
@@ -18,6 +19,7 @@ export const download = async (bucketName, path, options = {}) => {
 };
 export const upload = async (bucketName, path, body, mimeType = 'application/json;charset=utf-8', options = {}) => {
     try {
+        const client = createClient();
         createLogger().log('PutObjectCommand:', {
             Bucket: bucketName,
             Key: path,
@@ -40,6 +42,7 @@ export const upload = async (bucketName, path, body, mimeType = 'application/jso
 };
 export const exists = async (bucketName, path, options = {}) => {
     try {
+        const client = createClient();
         createLogger().log('HeadObjectCommand:', {
             Bucket: bucketName,
             Key: path,

package/s3/client.d.ts

@@ -1,2 +1,2 @@
-import { S3Client } from '@aws-sdk/client-s3';
-export declare const client: S3Client;
+import { S3Client, type S3ClientConfig } from '@aws-sdk/client-s3';
+export declare const createClient: (options?: S3ClientConfig) => S3Client;

package/s3/client.js

@@ -1,10 +1,12 @@
 import { S3Client } from '@aws-sdk/client-s3';
 import { getRegion, getLocalstackHost, getLocalstackPort, isLocal } from '@vyriy/env';
-const options = isLocal()
-    ? {
-        region: getRegion(),
-        endpoint: `http://${getLocalstackHost()}:${getLocalstackPort()}`,
-        forcePathStyle: true,
-    }
-    : {};
-export const client = new S3Client(options);
+export const createClient = (options = {}) => {
+    const defaultOptions = isLocal()
+        ? {
+            region: getRegion(),
+            endpoint: `http://${getLocalstackHost()}:${getLocalstackPort()}`,
+            forcePathStyle: true,
+        }
+        : {};
+    return new S3Client({ ...defaultOptions, ...options });
+};

package/sns/actions.js

@@ -1,5 +1,6 @@
-import { client } from './client.js';
+import { createClient } from './client.js';
 export const publish = async (topicArn, message, options = {}) => {
+    const client = createClient();
     await client.publish({
         TopicArn: topicArn,
         Message: message,

package/sns/client.d.ts

@@ -1,2 +1,2 @@
-import { SNS } from '@aws-sdk/client-sns';
-export declare const client: SNS;
+import { SNS, type SNSClientConfig } from '@aws-sdk/client-sns';
+export declare const createClient: (options?: SNSClientConfig) => SNS;

package/sns/client.js

@@ -1,2 +1,2 @@
 import { SNS } from '@aws-sdk/client-sns';
-export const client = new SNS({});
+export const createClient = (options = {}) => new SNS(options);

package/ssm/actions.js

@@ -1,9 +1,10 @@
 import { GetParameterCommand, GetParametersCommand } from '@aws-sdk/client-ssm';
 import { createLogger } from '@vyriy/logger';
 import { toError } from '@vyriy/error';
-import { client } from './client.js';
+import { createClient } from './client.js';
 export const getParameter = async (parameterName, decrypted = true) => {
     try {
+        const client = createClient();
         const logger = createLogger();
         logger.log('GetParameterCommand:', parameterName, decrypted);
         const response = await client.send(new GetParameterCommand({ Name: parameterName, WithDecryption: decrypted }));
@@ -18,6 +19,7 @@ export const getParameter = async (parameterName, decrypted = true) => {
 };
 export const getParameters = async (parameterNames, decrypted = true) => {
     try {
+        const client = createClient();
         const logger = createLogger();
         logger.log('GetParametersCommand:', parameterNames, decrypted);
         const response = await client.send(new GetParametersCommand({ Names: parameterNames, WithDecryption: decrypted }));

package/ssm/client.d.ts

@@ -1,2 +1,2 @@
-import { SSMClient } from '@aws-sdk/client-ssm';
-export declare const client: SSMClient;
+import { SSMClient, type SSMClientConfig } from '@aws-sdk/client-ssm';
+export declare const createClient: (options?: SSMClientConfig) => SSMClient;

package/ssm/client.js

@@ -1,2 +1,2 @@
 import { SSMClient } from '@aws-sdk/client-ssm';
-export const client = new SSMClient({});
+export const createClient = (options = {}) => new SSMClient(options);