{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"aws-appsync","version":"0.1.0"},"spec":{"agents_md":"---\ndescription: 'Production-grade guidance for AWS AppSync Event API handlers using APPSYNC_JS runtime restrictions, utilities, modules, and datasource patterns'\napplyTo: '**/*.{graphql,gql,vtl,ts,js,mjs,cjs,json,yml,yaml}'\n---\n\n# AWS AppSync Event API Instructions\n\nUse these instructions when implementing AWS AppSync **Event API** handlers (`onPublish`, `onSubscribe`) with the `APPSYNC_JS` runtime.\n\n## Scope And Contract\n\n- Design handlers around channel namespace flow: `onPublish` runs before broadcast, `onSubscribe` runs on subscription attempts.\n- Keep event contracts explicit and stable. Treat channel path and payload shape as API contracts.\n- Prefer additive changes for payload fields and avoid breaking existing subscribers.\n\n## Data Sources Map (Event API)\n\nUse data sources intentionally based on event workflow needs:\n\n- Lambda: custom compute, transformation, orchestration, external AWS/service integrations.\n- DynamoDB: low-latency event/state persistence and key-based reads/writes.\n- RDS (Aurora): relational checks, joins, and stronger relational integrity use cases.\n- EventBridge: route events into broader event-driven architectures.\n- OpenSearch: search and analytics over event data.\n- HTTP endpoints: external APIs or AWS service APIs over HTTP.\n- Bedrock: model inference and AI enrichment in event pipelines.\n\nPrefer combining multiple data sources only when each hop has a clear reason (auth, persistence, enrichment, routing).\n\n## Data Source Setup And IAM (Required)\n\n- Create data sources at the Event API level, then attach them as namespace integrations.\n- If using a service role, grant only required actions (least privilege).\n- Trust policy principal must allow `appsync.amazonaws.com` to assume the role.\n- Restrict trust with conditions when possible:\n  - `aws:SourceAccount` to your account.\n  - `aws:SourceArn` to a specific AppSync API ARN (or tightly scoped pattern).\n- Do not reuse broad, cross-service IAM roles for AppSync data source access.\n\n## Runtime Restrictions (Must Follow)\n\nThe `APPSYNC_JS` runtime is a constrained JavaScript subset. Write code for this environment, not for full Node.js.\n\n- Do not use async patterns: no promises, `async/await`, or background async workflows.\n- Do not use unsupported statements/operators: `try/catch/finally`, `throw`, `while`, C-style `for(;;)`, `continue`, labels, unsupported unary operators.\n- Do not rely on network or file system access from runtime code. Use AppSync data sources for I/O.\n- Do not use recursion or pass functions as function arguments.\n- Do not rely on classes or advanced runtime features outside documented support.\n- Prefer `for-of` / `for-in` loops when iteration is needed.\n\n## Handler Flow Patterns\n\n- For handlers without data source integration, return transformed `ctx.events` directly.\n- For handlers with data sources, use object form with `request(ctx)` and `response(ctx)`.\n- Use `runtime.earlyReturn(...)` when business logic decides to skip data source invocation and response mapping.\n- Use `ctx.info.channel.path`, `ctx.info.channel.segments`, `ctx.info.channelNamespace.name`, and `ctx.info.operation` to drive routing logic.\n- For `onPublish` with data source integration, return the event list to broadcast from `response(ctx)`.\n- For `onSubscribe` with data source integration, include a `response(ctx)` function (it can be empty when no follow-up mapping is needed).\n\n### `ctx.prev.result` vs `ctx.stash` (Pipeline Guidance)\n\n- If resolver/functions execute step-by-step and the next step depends on the previous step output, use `ctx.prev.result`.\n- Use `ctx.prev.result` as the default data handoff mechanism between consecutive pipeline functions.\n- Use `ctx.stash` when you need shared data across multiple pipeline stages that is not just the immediate previous result.\n- Store only small, intentional metadata in `ctx.stash` (for example flags, IDs, correlation context), not large payload copies.\n- Do not duplicate full previous results into `ctx.stash` when `ctx.prev.result` already provides the needed value.\n\n## Error And Authorization Flow\n\n- Do not use `throw` in handlers. Use `util.error(...)` and `util.appendError(...)` patterns supported by AppSync runtime.\n- For publish failures, return explicit runtime errors with safe messages (no internals).\n- For business-level authorization rejection at handler level, use the documented unauthorized utility in handler code.\n- Keep error payloads non-sensitive. Never expose secrets, raw stack traces, or internal identifiers.\n\n## Built-In Utilities\n\nUse `util` for runtime-safe helpers.\n\n- Encoding utilities:\n  - `util.urlEncode`, `util.urlDecode`\n  - `util.base64Encode`, `util.base64Decode`\n- Runtime utility:\n  - `runtime.earlyReturn(obj)` to stop current handler execution and skip data source + response evaluation.\n\n## Built-In Modules\n\nUse official modules from `@aws-appsync/utils` and keep code declarative.\n\n- DynamoDB module import:\n  - `import * as ddb from '@aws-appsync/utils/dynamodb'`\n- RDS module import:\n  - `import { ... } from '@aws-appsync/utils/rds'`\n\n### DynamoDB Usage\n\nPrefer module helpers over handwritten request objects where possible.\n\n- Core helpers include: `get`, `put`, `remove`, `update`, `query`, `scan`, `sync`.\n- Batch helpers: `batchGet`, `batchPut`, `batchDelete`.\n- Transaction helpers: `transactGet`, `transactWrite`.\n- For `update`, prefer operation helpers like increment/append/add/remove for safe patch-style mutations.\n- Model keys and indexes for query-first access. Avoid `scan` unless justified.\n- Use conditions for correctness and optimistic concurrency when needed.\n- For bursty publish flows, prefer `batchPut`/`batchDelete` (or `transactWrite` when atomicity is required) over many single-item operations.\n- Keep DynamoDB batch sizes within service/API limits and chunk inputs deterministically.\n\n### Lambda Usage\n\nFor Event API Lambda data source requests, use:\n\n- `operation: 'Invoke'`\n- optional `invocationType: 'RequestResponse' | 'Event'`\n- `payload` shaped explicitly for the Lambda contract\n\nGuidance:\n\n- Use `RequestResponse` when handler flow depends on Lambda output.\n- Use `Event` only for fire-and-forget side effects.\n- Validate `ctx.result` in `response(ctx)` and map to the exact outgoing event shape.\n- In Event API handlers, Lambda operation support is `Invoke`; do not rely on GraphQL-style `BatchInvoke` here.\n- If you need batching with Lambda in Event API flows, send an array payload in one `Invoke` and implement item-level aggregation/partial-failure handling inside Lambda.\n\n### Direct Lambda Integration (No Handler Code)\n\nYou can configure namespace handlers with direct Lambda integrations (`Behavior: DIRECT`) instead of writing `onPublish`/`onSubscribe` code.\n\n- `REQUEST_RESPONSE` mode:\n  - `onPublish` Lambda returns `{ events?: OutgoingEvent[], error?: string }`.\n  - `onSubscribe` Lambda returns `null` for success or `{ error: string }` for rejection.\n- `EVENT` mode:\n  - Invocation is asynchronous; AppSync does not wait for a Lambda response.\n  - For publish, events continue broadcasting as usual.\n- If Lambda returns `error` in request/response mode, it is logged when logging is enabled, and not sent back as a detailed internal error payload.\n\nPrefer direct Lambda integration when the entire namespace behavior can be centralized in Lambda and you do not need APPSYNC_JS request/response mapping logic.\n\n### HTTP/EventBridge/RDS/OpenSearch/Bedrock\n\nWhen using non-DynamoDB data sources:\n\n- HTTP: return `resourcePath`, `method`, optional `params` (`headers`, `query`, `body`); check `ctx.result.statusCode`, `ctx.result.body`, and `ctx.error`.\n- EventBridge: use `operation: 'PutEvents'` and build deterministic event entries from `ctx.events`.\n- RDS: prefer SQL helpers and `createPgStatement`/`createMySQLStatement`; do not interpolate unsafe SQL.\n- OpenSearch: keep request path/params explicit and map only required fields from `ctx.result`.\n- Bedrock: define `operation` (`InvokeModel` or `Converse`) explicitly and include prompt-injection safeguards.\n\n## Batch Operations (Required Guidance)\n\n- Prefer batching where the target data source natively supports it and event semantics allow grouping.\n- DynamoDB:\n  - Use `batchGet`, `batchPut`, `batchDelete` for non-atomic bulk operations.\n  - Use `transactGet`, `transactWrite` when atomic all-or-nothing behavior is required.\n  - Validate and cap per-request item counts; chunk large batches.\n- Lambda:\n  - Event API JS handler requests use `operation: 'Invoke'` with optional `invocationType`.\n  - There is no Event API `BatchInvoke` operation in handler request objects.\n  - For pseudo-batch Lambda patterns, send list payloads to one invoke and return deterministic per-item result structures.\n- Keep ordering guarantees explicit: if downstream consumers depend on order, preserve and document ordering keys.\n\n## Security And Data Safety\n\n- Treat `ctx.identity`, headers, and payload fields as untrusted input.\n- Enforce least-privilege IAM per data source.\n- Add validation before write operations and before forwarding transformed events.\n- Never hardcode secrets in handler code.\n- For public usage, keep defaults conservative (deny/unauthorized on invalid states).\n\n## Tooling, TypeScript, And Build\n\n- Use `@aws-appsync/eslint-plugin` (`plugin:@aws-appsync/base` at minimum).\n- Use `plugin:@aws-appsync/recommended` when TypeScript tooling is configured.\n- TypeScript is not executed directly by AppSync runtime. Transpile to supported JavaScript before deployment.\n- Bundle with externalized `@aws-appsync/utils` imports and source maps for debugging.\n\n## Observability And Operations\n\n- Enable CloudWatch logging for handlers and datasource integration.\n- Log with structured, low-cardinality fields (channel namespace/path, operation, request id).\n- Add alarmable signals: handler errors, datasource errors, latency regression.\n- Keep response transformations deterministic and test with multi-event payloads.\n\n## Minimum Quality Checklist\n\n- [ ] Uses only APPSYNC_JS-supported runtime features.\n- [ ] No `throw`, no async/promise usage, no unsupported loop/control constructs.\n- [ ] Error flow uses runtime-supported utilities and returns non-sensitive messages.\n- [ ] `onPublish` and `onSubscribe` behavior is explicit and tested.\n- [ ] Data source request/response mapping is deterministic and schema-safe.\n- [ ] Lambda/DynamoDB contracts are documented and validated.\n- [ ] Linting with `@aws-appsync/eslint-plugin` is enabled.\n","description":"Production-grade guidance for AWS AppSync Event API handlers using APPSYNC_JS runtime restrictions, utilities, modules, and datasource patterns","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/aws-appsync.instructions.md"},"manifest":{}},"content_hash":[55,12,9,176,105,7,146,0,23,109,78,102,255,133,229,70,74,218,139,23,26,68,251,100,9,142,172,215,75,119,91,193],"trust_level":"unsigned","yanked":false}