ai-prompt-postman-react-library

Act as a senior TypeScript SDK, React library, and Next.js architecture expert.

Your job is to generate a production-ready set of TypeScript libraries and supporting app-layer code for a Next.js website that wraps an API into strongly typed objects, clients, hooks, and domain models.

I will provide:

* a Postman collection
* a Postman environment
* one or more PDF documents with API, workflow, or business rules
* optionally example payloads, error responses, and usage notes

What I want you to build:

* a clean monorepo or workspace structure suitable for a Next.js codebase
* a strongly typed API client generated and/or derived from the Postman collection and environment
* rich domain models as typed objects, not just thin request wrappers
* React and Next.js friendly libraries for use in a production web app
* code that is maintainable, documented, and practical for real use by engineers

Main goal:
Create a set of libraries that make the API feel like a well-designed TypeScript SDK plus React and Next.js integration layer, with strong typing, clean abstractions, and excellent developer experience.

Deliverables:

1. Recommend the best project structure first.
2. Then generate the code.
3. Use TypeScript throughout.
4. Prefer modern React and Next.js patterns.
5. Separate generated code from handwritten code where appropriate.
6. Use the Postman collection as the source of truth for endpoints and requests.
7. Use the PDFs to infer business rules, field meanings, workflows, validation rules, enums, and domain concepts.
8. Use the Postman environment to resolve variables, auth details, base URLs, and environments.
9. Where the source material is ambiguous, make the safest practical assumption and clearly flag it.
10. Do not stay at toy-example level. Build this as if it will actually be used by a frontend team.

Architecture requirements:

* Optimise for Next.js App Router by default unless the source material strongly suggests otherwise
* Structure the code so shared libraries can be consumed cleanly by a Next.js app
* Be explicit about what runs in:

  * server components
  * client components
  * route handlers
  * server actions
  * middleware, only if genuinely needed
* Keep browser-only concerns separate from server-only concerns
* Prevent accidental leakage of secrets into client bundles
* Support SSR, RSC, and client-side data fetching patterns where appropriate
* Design for future extension as the API evolves

Suggested package boundaries:

* packages/api-generated - generated transport client, endpoint types, schemas, raw DTOs
* packages/api-core - handwritten client wrappers, shared request logic, auth-safe request helpers, retries, error normalization
* packages/domain - domain models, mappers, business-level types, enums, validators
* packages/react-sdk - client-safe React hooks, query helpers, mutation hooks, providers
* packages/next-sdk - Next.js specific helpers for server components, route handlers, server actions, cookies/headers integration where appropriate
* packages/utils - shared utility code
* apps/web - example or real Next.js app integration
* tooling/codegen - scripts to regenerate client code from the Postman collection and related inputs

Strong typing requirements:

* Generate or derive request and response types for every endpoint
* Create domain-level types and objects where useful, not only transport DTOs
* Distinguish transport models from domain models
* Infer enums, unions, nullable fields, optional fields, discriminated unions, pagination structures, and error shapes where possible
* Normalize naming conventions across inconsistent source material
* Surface areas of uncertainty explicitly
* Avoid "any" unless absolutely unavoidable, and explain why if used

Next.js requirements:

* Default to Next.js App Router patterns
* Show how the libraries should be used in:

  * server components
  * client components
  * route handlers
  * server actions
* Clearly mark modules with "use client" only where required
* Use server-only boundaries where appropriate
* Show safe environment variable handling for server-only and public values
* Show how auth/session state should be handled in Next.js if auth details are present in the inputs
* Explain which API access patterns should happen on the server versus in the browser
* Include cache/revalidation guidance where appropriate
* If TanStack Query is used, show how it integrates with App Router and hydration
* Prefer minimal framework coupling outside the Next.js integration package

React requirements:

* Build React-friendly packages suitable for a Next.js web application
* Include:

  * typed hooks for reads and mutations
  * query key helpers
  * loading/error/data state patterns
  * provider setup if useful
  * examples of component usage
* Prefer TanStack Query unless there is a strong reason not to
* Keep the generic React layer reusable outside Next.js where possible

Code generation requirements:

* Use the Postman collection to derive:

  * endpoints
  * methods
  * params
  * headers
  * auth patterns
  * example payloads
  * response shapes where possible
* If the Postman collection is insufficient on its own, supplement from PDFs and examples
* Propose a repeatable codegen pipeline
* Clearly separate:

  * generated client layer
  * handwritten adapters and mappers
  * handwritten domain logic
  * Next.js integration code
* Include scripts and instructions for regenerating the code

PDF interpretation requirements:

* Read the PDFs carefully and extract:

  * business terminology
  * lifecycle states
  * validation rules
  * workflow constraints
  * permissions and roles if present
  * edge cases
  * domain relationships
* Convert those into useful typed abstractions, validators, docs, and comments where appropriate
* If the PDFs contradict the Postman collection, identify the conflict and recommend the most likely source of truth

Output format:
Work in this order:

Phase 1 - Discovery

* Summarize what you found in the Postman collection, environment, and PDFs
* List endpoints, auth model, major resources, workflows, and inconsistencies
* Identify missing or weakly specified areas

Phase 2 - Architecture proposal

* Propose the workspace and package structure
* Explain package responsibilities
* Explain generated vs handwritten boundaries
* Explain naming conventions and typing strategy
* Explain Next.js server/client boundaries

Phase 3 - Implementation

* Generate the full codebase or as much of it as possible
* Include all key files with paths
* Include package.json files, tsconfig setup, build config, and scripts
* Include README documentation
* Include usage examples for server components, client components, route handlers, and server actions
* Include test examples for critical areas
* Include regeneration workflow

Phase 4 - Gaps and decisions

* List assumptions made
* List unresolved ambiguities
* List recommended follow-up inputs that would improve accuracy

Implementation standards:

* Production-grade TypeScript
* Clear naming
* Small focused modules
* Good comments only where helpful
* Sensible error handling
* No unnecessary abstraction
* Prefer clarity over cleverness
* Keep public APIs ergonomic
* Make the SDK pleasant to use by frontend engineers
* Keep generated output deterministic where possible

Important working rules:

* Do not just describe the architecture. Actually generate the code.
* Do not stop at high-level recommendations.
* Do not rely on OpenAPI unless you first derive it from the Postman collection or explain why that conversion is needed.
* Do not flatten everything into one package unless there is a compelling reason.
* Do not expose awkward raw API shapes directly if a better typed abstraction is possible.
* Where needed, create mappers from transport DTOs to domain objects.
* Preserve traceability back to source endpoints and documents.
* Be careful not to put secrets, admin tokens, or server-only config into client-side code.
* Be explicit when code is intended for server-only execution.

Technical preferences:

* TypeScript
* Next.js App Router
* TanStack Query for client-side query and mutation hooks
* Zod for runtime validation where helpful
* Fetch-based client unless the source material strongly suggests another transport
* Workspace tooling of your choice, but keep it simple and maintainable
* pnpm preferred unless there is a strong reason otherwise

Before coding, ask yourself:

* What should be generated?
* What should be handwritten?
* What belongs in transport vs domain?
* What belongs in generic React vs Next.js specific integration?
* What should run on the server vs the client?
* What will make this easy to maintain six months from now?

When I upload the files, start by analyzing them and proposing the package structure, then generate the implementation.

Be decisive. Make sensible implementation choices and generate code rather than waiting for more clarification unless something is genuinely blocking.