anton-bakker-amplify-utils

Utilities for AWS Amplify apps with safe configuration and structured error handling.

Highlights

• No hardcoded environment: consumers provide Amplify configuration (amplify_outputs.json) and create their own clients
• No console logging in library code (to avoid issues in Amplify/React apps)
• No thrown exceptions in exported helpers; functions return structured errors
• aws-amplify and react are peerDependencies (not bundled)

Installation

• npm i anton-bakker-amplify-utils
• Also install peer deps in your app:
  • npm i aws-amplify@^6 react@^19

Usage (Amplify config and client)

import { Amplify } from 'aws-amplify';
import outputs from './amplify_outputs.json';
import { amplifyConfig } from 'anton-bakker-amplify-utils';
import { generateClient } from 'aws-amplify/data';

// App configures Amplify
Amplify.configure(outputs);

// Optional helper from this package (uses same config)
amplifyConfig(outputs);

// Example: create data client in your app
const client = generateClient({ authMode: 'userPool' });

Structured errors (no throws) Both TerraIndex and OMS4Business return an object with data and optional error. No exceptions are thrown.

import TerraIndex from 'anton-bakker-amplify-utils/dist/TerraIndex';

const result = await TerraIndex({
  url: '/some/terraindex/endpoint',
  options: {
    params: { foo: 'bar' },
    body: { SearchFilter: 'term' }
  }
});

if (result.error) {
  // result.error = { code, message, status?, details? }
  // handle gracefully
} else {
  // result.data is an array of records (arrays of key-value maps)
}

import OMS4Business from 'anton-bakker-amplify-utils/dist/OMS4Business';

const res = await OMS4Business({ method: 'GET', endpoint: '/locations', options: { per_page: 100 } });

if (res.error) {
  // res.error.code is 'HTTP_ERROR' | 'UNKNOWN_ERROR' | 'INVALID_RESPONSE'
} else {
  // res.data contains the aggregated records
}

API surface

• amplifyConfig(config): configures Amplify with a consumer-provided config (e.g., amplify_outputs.json). Returns the same config for convenience.
• TerraIndex(input): returns { data, error? }
• OMS4Business({ method, endpoint, options? }): returns { data, error? }
• DisplayJson({ jsonString })
• User context utilities: UserProvider, useUser, useUserInfo, etc.

Breaking changes

• v3.0.0
  • TerraIndex and OMS4Business no longer throw. They now return { data, error? } with structured errors.
  • No console logging anywhere in helpers.
• v2.0.0
  • amplifyConfig now requires an external config (client) from the app; the library no longer imports amplify_outputs.json.
  • aws-amplify and react moved to peerDependencies (added as devDependencies for local builds).

Automated publishing without OTP (automation token)

• Create an npm Automation Token (bypasses OTP for publish) in the npm website
  • npmjs.com -> your profile -> Access Tokens -> Generate New Token -> type: Automation
  • Restrict it to this package if using fine-grained tokens, and consider CIDR restrictions for extra safety
• Store the token securely (recommended: AWS Secrets Manager) using your BeyondAmbition profile
  • aws --profile BeyondAmbition secretsmanager create-secret
    --name npm/automation-token/anton-bakker-amplify-utils
    --secret-string ''
• This repo includes a publish helper that fetches the token securely and publishes using a temporary .npmrc
  • NPM_SECRET_NAME can be overridden if you use a different secret name

Usage

• Default profile and secret name:
  • AWS_PROFILE=BeyondAmbition npm run release:publish
• Override secret name or registry if needed:
  • AWS_PROFILE=BeyondAmbition NPM_SECRET_NAME=npm/automation-token/another-secret npm run release:publish

Security notes

• The token is never printed to the console; it is fetched into memory and written to a temporary .npmrc that is deleted after publish
• Keep your AWS credentials secure. Revoke the automation token immediately if you suspect compromise

License MIT