@shaykec/bridge 0.4.25 → 0.4.27

package/modules/api-design/game.yaml

@@ -0,0 +1,113 @@
+games:
+  - type: speed-round
+    title: "HTTP Method Sprint"
+    rounds:
+      - question: "Create a new user account. Which HTTP method and status code?"
+        options:
+          - "GET 200"
+          - "POST 201"
+          - "PUT 200"
+          - "PATCH 201"
+        answer: 1
+        timeLimit: 14
+      - question: "Delete a resource. Which method and status?"
+        options:
+          - "DELETE 200"
+          - "DELETE 204"
+          - "POST 200"
+          - "GET 204"
+        answer: 1
+        timeLimit: 14
+      - question: "Fetch a single user by ID (read-only). Which method?"
+        options:
+          - "POST 200"
+          - "GET 200"
+          - "PUT 200"
+          - "PATCH 200"
+        answer: 1
+        timeLimit: 12
+      - question: "Update an existing resource (partial update). Which method?"
+        options:
+          - "PUT 200"
+          - "PATCH 200"
+          - "POST 200"
+          - "GET 200"
+        answer: 1
+        timeLimit: 14
+      - question: "Resource not found. Which status code?"
+        options:
+          - "400 Bad Request"
+          - "404 Not Found"
+          - "500 Internal Server Error"
+          - "204 No Content"
+        answer: 1
+        timeLimit: 14
+      - question: "Replace an existing resource entirely (full update). Which method?"
+        options:
+          - "PATCH 200"
+          - "PUT 200"
+          - "POST 200"
+          - "GET 200"
+        answer: 1
+        timeLimit: 14
+      - question: "List all items in a collection. Which method and status?"
+        options:
+          - "GET 200"
+          - "POST 201"
+          - "GET 201"
+          - "PUT 200"
+        answer: 0
+        timeLimit: 12
+      - question: "Invalid request body (e.g. missing required field). Which status?"
+        options:
+          - "404 Not Found"
+          - "400 Bad Request"
+          - "422 Unprocessable Entity"
+          - "500 Internal Server Error"
+        answer: 1
+        timeLimit: 15
+      - question: "Request succeeded, no response body to return. Which status?"
+        options:
+          - "200 OK"
+          - "204 No Content"
+          - "202 Accepted"
+          - "201 Created"
+        answer: 1
+        timeLimit: 14
+      - question: "Request accepted for async processing. Which status?"
+        options:
+          - "200 OK"
+          - "201 Created"
+          - "202 Accepted"
+          - "204 No Content"
+        answer: 2
+        timeLimit: 14
+
+  - type: classify
+    title: "API Pattern Classifier"
+    categories:
+      - name: "REST"
+        color: "#58a6ff"
+      - name: "GraphQL"
+        color: "#a371f7"
+      - name: "RPC"
+        color: "#d29922"
+    items:
+      - text: "GET /users/123, POST /orders, DELETE /products/456 — resources and HTTP verbs."
+        category: "REST"
+      - text: "Single endpoint, client sends { query: '{ users { id name } }' } — flexible field selection."
+        category: "GraphQL"
+      - text: "POST /rpc/CreateUser with { name, email } — procedure-oriented, not resource-oriented."
+        category: "RPC"
+      - text: "GET /api/v1/orders?status=shipped — standard HTTP, URI as resource identifier."
+        category: "REST"
+      - text: "Client specifies exactly which fields to fetch; no over- or under-fetching."
+        category: "GraphQL"
+      - text: "gRPC, protobuf, methods like GetUser, CreateOrder — strong typing, often binary."
+        category: "RPC"
+      - text: "HATEOAS — links in response point to related resources and actions."
+        category: "REST"
+      - text: "Mutations and queries; schema defines types and resolvers; introspection supported."
+        category: "GraphQL"
+      - text: "JSON-RPC: { jsonrpc: '2.0', method: 'subtract', params: [5, 3] }."
+        category: "RPC"

package/modules/api-design/module.yaml

@@ -0,0 +1,45 @@
+slug: api-design
+title: "API Design -- REST, GraphQL, and Contract-First Thinking"
+version: 1.0.0
+description: "Design production-ready APIs with REST, GraphQL, and contract-first practices."
+category: architecture
+tags: [api, rest, graphql, api-design, contracts, openapi]
+difficulty: intermediate
+
+xp:
+  read: 15
+  walkthrough: 40
+  exercise: 25
+  quiz: 20
+  quiz-perfect-bonus: 10
+  game: 25
+  game-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 20
+  guided: 50
+
+prerequisites: []
+related: [system-design, solid-principles]
+
+triggers:
+  - "How do I design a good REST API?"
+  - "REST vs GraphQL — when to use which?"
+  - "What is contract-first API design?"
+  - "How do I version an API?"
+
+visuals:
+  diagrams: [diagram-mermaid, diagram-architecture]
+  quiz-types: [quiz-matching, quiz-fill-blank]
+  game-types: [speed-round, classify]
+  playground: bash
+  slides: true
+
+sources:
+  - url: "https://github.com/microsoft/api-guidelines"
+    label: "Microsoft REST API Guidelines"
+    type: docs
+  - url: "https://cloud.google.com/apis/design"
+    label: "Google API Design Guide"
+    type: docs

package/modules/api-design/quick-ref.md

@@ -0,0 +1,73 @@
+# API Design Quick Reference
+
+## REST
+
+| Verb | Action | Example |
+|------|--------|---------|
+| GET | Read | GET /users/42 |
+| POST | Create | POST /users |
+| PUT | Replace | PUT /users/42 |
+| PATCH | Partial update | PATCH /users/42 |
+| DELETE | Remove | DELETE /users/42 |
+
+**Conventions:** Plural nouns, hierarchy in URL, consistent casing
+
+## REST vs GraphQL
+
+| REST | GraphQL |
+|------|---------|
+| Many endpoints | Single endpoint |
+| Fixed responses | Client-specified fields |
+| HTTP cache | Custom cache |
+| Simpler | More flexible |
+
+## Status Codes
+
+| Code | Meaning |
+|------|---------|
+| 200 | OK |
+| 201 | Created |
+| 400 | Bad Request |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not Found |
+| 429 | Too Many Requests |
+| 500 | Server Error |
+
+## Versioning
+
+- **URL:** `/v1/users` — clear, cacheable
+- **Header:** `Accept: application/vnd.api+json;version=2`
+
+## Pagination
+
+- **Offset:** `?offset=20&limit=10` — simple, can drift
+- **Cursor:** `?cursor=abc&limit=10` — stable for feeds
+
+## Auth
+
+| Method | Use |
+|--------|-----|
+| API Key | Server-to-server |
+| OAuth 2.0 | Delegated user access |
+| JWT | Stateless, `Authorization: Bearer <token>` |
+
+## Error Body
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "...",
+    "details": []
+  }
+}
+```
+
+## Rate Limit Headers
+
+```
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 42
+Retry-After: 60
+```

package/modules/api-design/quiz.md

@@ -0,0 +1,100 @@
+# API Design Quiz
+
+## Question 1
+
+In REST, which HTTP method should be used to create a new resource?
+
+A) GET
+B) PUT
+C) POST
+D) PATCH
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: POST is used to create a new resource. The client sends the representation in the body; the server assigns the ID and returns 201 Created. PUT typically replaces a resource at a known URL. -->
+
+## Question 2
+
+When is GraphQL typically preferred over REST?
+
+A) When you need simple CRUD operations
+B) When clients have varying data needs and want to avoid over-fetching
+C) When HTTP caching is the top priority
+D) When you have no frontend team
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: GraphQL lets clients request exactly the fields they need. Mobile apps and varied clients benefit from avoiding over-fetching and under-fetching. REST is often simpler for straightforward CRUD. -->
+
+## Question 3
+
+Contract-first API design means:
+
+A) Writing the API specification before implementing the backend
+B) Signing a legal contract before building
+C) Designing for backward compatibility only
+D) Using REST exclusively
+
+<!-- ANSWER: A -->
+<!-- EXPLANATION: Contract-first means defining the API (e.g., OpenAPI spec or GraphQL schema) before writing server code. This enables client generation, mocks, and parallel work. -->
+
+## Question 4
+
+For paginating a feed of posts that changes frequently, which strategy is best?
+
+A) Offset-based (?page=5)
+B) Cursor-based (?cursor=abc123)
+C) No pagination
+D) Random access by ID
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Cursor-based pagination is stable when data is inserted or deleted. Offset-based can produce duplicates or skipped items. For feeds and infinite scroll, cursor is preferred. -->
+
+## Question 5
+
+What does a 429 status code mean?
+
+A) Server error
+B) Not found
+C) Too many requests (rate limited)
+D) Unauthorized
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: 429 Too Many Requests indicates the client has exceeded the rate limit. The response should include Retry-After to indicate when to retry. -->
+
+## Question 6
+
+Which authentication method is best for delegated user access (e.g., "this app can read my data")?
+
+A) API key in the query string
+B) OAuth 2.0
+C) Basic auth
+D) No authentication
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: OAuth 2.0 is designed for delegated access: the user authorizes an app to act on their behalf. API keys are better for server-to-server. Basic auth sends credentials with every request and is less suitable for third-party apps. -->
+
+## Question 7
+
+<!-- VISUAL: matching -->
+
+Match each HTTP method to its typical REST operation:
+
+A) GET → 1) Create a new resource
+B) POST → 2) Replace a resource at a known URL
+C) PUT → 3) Retrieve a resource
+D) DELETE → 4) Remove a resource
+
+<!-- ANSWER: A3,B1,C2,D4 -->
+<!-- EXPLANATION: GET retrieves (3). POST creates (1). PUT replaces at a known URL (2). DELETE removes (4). -->
+
+## Question 8
+
+<!-- VISUAL: fill-blank -->
+
+Complete the RESTful endpoint URL pattern for a nested resource (orders belonging to a user):
+
+```
+/users/___0___/orders
+```
+
+<!-- ANSWER: :id -->
+<!-- EXPLANATION: REST uses path segments for resource IDs. Common patterns are :id, {id}, or :userId. The placeholder represents the user identifier in the URL. -->

package/modules/api-design/resources.md

@@ -0,0 +1,55 @@
+# API Design — Resources
+
+## Official Guidelines
+
+- [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines) — REST best practices from Microsoft.
+- [Google API Design Guide](https://cloud.google.com/apis/design) — Google's API design principles.
+- [GraphQL Specification](https://spec.graphql.org/) — Official GraphQL spec.
+
+## REST and HTTP
+
+- [REST API Tutorial](https://restfulapi.net/) — REST concepts and examples.
+- [HTTP Status Codes](https://httpstatuses.com/) — Quick reference for status codes.
+- [RFC 7807 — Problem Details](https://tools.ietf.org/html/rfc7807) — Standard error format.
+
+## GraphQL
+
+- [GraphQL.org](https://graphql.org/) — Official docs and learning resources.
+- [How to GraphQL](https://www.howtographql.com/) — Full-stack GraphQL tutorial.
+- [Apollo GraphQL](https://www.apollographql.com/docs/) — Client and server tooling.
+
+## Contract-First and OpenAPI
+
+- [OpenAPI Specification](https://swagger.io/specification/) — OpenAPI 3.0 reference.
+- [Stoplight](https://stoplight.io/) — API design and documentation tools.
+- [Postman](https://www.postman.com/) — API testing and documentation.
+
+## Articles and Books
+
+- [Martin Fowler — Richardson Maturity Model](https://martinfowler.com/articles/richardsonMaturityModel.html) — REST maturity levels.
+- [InfoQ — REST vs GraphQL](https://www.infoq.com/articles/rest-graphql/) — Comparison articles.
+- **RESTful Web APIs** by Leonard Richardson — REST design in depth.
+- **Designing Web APIs** by Brenda Jin — API design patterns.
+
+## Videos
+
+- [REST API Design — Java Brains](https://www.youtube.com/watch?v=QpQxRd1Y2xY) — REST design principles.
+- [GraphQL in 5 Minutes](https://www.youtube.com/watch?v=ZQL7tL2S0oQ) — Quick GraphQL intro.
+- [API Design — Google I/O](https://www.youtube.com/results?search_query=google+io+api+design) — Conference talks.
+
+## Podcasts
+
+- [APIs You Won't Hate](https://apisyouwonthate.com/podcast/) — Phil Sturgeon. API design, versioning, and developer experience.
+- [Software Engineering Daily — API Design](https://softwareengineeringdaily.com/?s=api+design) — Technical episodes on REST, GraphQL, and gRPC decisions.
+- [Changelog — API Economy](https://changelog.com/podcast) — Episodes on public API design and developer relations.
+
+## Interactive and Visual
+
+- [Swagger Editor](https://editor.swagger.io/) — Write and visualize OpenAPI specs in the browser with live preview.
+- [Hoppscotch](https://hoppscotch.io/) — Open-source API testing tool — explore REST, GraphQL, and WebSocket APIs interactively.
+- [GraphQL Playground (Apollo)](https://www.apollographql.com/docs/graphos/explorer/) — Interactive GraphQL IDE for exploring schemas and running queries.
+
+## Courses
+
+- [Designing RESTful APIs (Udacity — free)](https://www.udacity.com/course/designing-restful-apis--ud388) — Short free course on REST principles and Flask implementation.
+- [How to GraphQL (free)](https://www.howtographql.com/) — Full-stack GraphQL tutorial covering fundamentals and frontend/backend tracks.

package/modules/api-design/walkthrough.md

@@ -0,0 +1,88 @@
+# API Design Walkthrough — Learn by Doing
+
+## Before We Begin
+
+REST APIs expose resources (nouns) via URLs and HTTP methods (verbs). Good design makes the API predictable and self-describing—clients can guess the shape of `GET /users/42` without reading docs.
+
+**Diagnostic question:** When you've consumed or built an API, what made it easy or frustrating to use? Was it URLs, documentation, error messages, or something else?
+
+**Checkpoint:** You can name at least one REST resource (e.g., users, orders) and one HTTP method beyond GET.
+
+---
+
+## Step 1: Model Resources
+
+<!-- hint:diagram mermaid-type="flowchart" topic="REST resource and HTTP method mapping" -->
+<!-- hint:code language="text" highlight="1,2" -->
+
+**Task:** You're building an API for a task manager. List 3–4 main resources (nouns). For each, write the URL pattern and which HTTP methods apply (GET, POST, PUT, PATCH, DELETE).
+
+**Question:** Why use `PATCH` instead of `PUT` for partial updates? When would you use `PUT`?
+
+**Checkpoint:** You have a clear resource model and URL structure.
+
+---
+
+## Step 2: Design a REST Endpoint
+
+<!-- hint:code language="json" highlight="1,5" -->
+
+**Task:** Design `GET /tasks?status=open&assignee=42` for listing tasks. Define: (1) query parameters, (2) response shape (fields), (3) status codes (200, 400, 401). Write a sample JSON response.
+
+**Question:** Should pagination be required or optional? What default `limit` would you use?
+
+**Checkpoint:** You have a complete endpoint spec with params and response.
+
+---
+
+## Step 3: REST vs GraphQL
+
+<!-- hint:buttons type="single" prompt="For a mobile app needing user + last 5 orders, which fits better?" options="REST (multiple requests),GraphQL (single query),Depends on use case" -->
+
+**Task:** A mobile app needs: user profile (name, avatar) + last 5 orders (id, date). Compare: (a) REST: how many requests? (b) GraphQL: one query. Write the GraphQL query.
+
+**Question:** When would REST with a compound endpoint (e.g., `GET /me?include=orders`) be simpler than GraphQL?
+
+**Checkpoint:** You can articulate when each approach fits.
+
+---
+
+## Step 4: Contract-First with OpenAPI
+
+<!-- hint:embed url="https://swagger.io/specification/" -->
+
+**Embed:** https://editor.swagger.io/
+
+**Task:** Add the `GET /tasks` endpoint to an OpenAPI spec. Include path, parameters, responses for 200 and 400. Use the standard OpenAPI 3.0 structure.
+
+**Question:** What can you generate from an OpenAPI spec? (clients, mocks, docs, tests)
+
+**Checkpoint:** You have a valid OpenAPI snippet for one endpoint.
+
+---
+
+## Step 5: Versioning Strategy
+
+**Task:** Your API has `GET /users` returning `{ id, name, email }`. You need to add `avatar_url` without breaking old clients. Describe two versioning approaches: (1) URL versioning, (2) additive change (backward compatible). Which would you choose and why?
+
+**Question:** When is additive change (adding optional fields) sufficient? When do you need a real new version?
+
+**Checkpoint:** You understand when to add vs when to version.
+
+---
+
+## Step 6: Error Handling
+
+**Task:** A client sends `POST /tasks` with `{ "title": "" }` — empty title is invalid. Design the error response: status code, body shape, and at least one header that would help a client.
+
+**Question:** Should the body use a custom structure or follow a standard (e.g., RFC 7807 Problem Details)?
+
+**Checkpoint:** You have a consistent error format with status and structured body.
+
+---
+
+## Step 7: Pagination and Rate Limiting
+
+**Task:** Add cursor-based pagination to `GET /tasks`. Define: (1) request params (`cursor`, `limit`), (2) response shape (tasks array + `next_cursor`), (3) behavior when no more pages. Then add a rate limit header (e.g., 100 req/min). What would you return when the limit is exceeded?
+
+**Checkpoint:** Pagination and rate limit are fully specified.

package/modules/clean-code/content.md

@@ -0,0 +1,136 @@
+# Clean Code — Naming, Functions, and Readability That Scales
+
+## Why Clean Code Matters
+
+Code is read far more often than it's written. Clean code reduces cognitive load, speeds onboarding, and makes changes safer.
+
+## Naming Conventions
+
+**Reveal intent:**
+```javascript
+// Bad
+const d = 86400;
+// Good
+const secondsPerDay = 86400;
+```
+
+**Avoid disinformation:** Don't use `accountList` if it's not a List. Use `accounts` or `accountGroup`.
+
+**Use pronounceable names:**
+```javascript
+// Bad
+const genymdhms = ...;
+// Good
+const generationTimestamp = ...;
+```
+
+**Use searchable names:** `MAX_ITEMS` is better than `7` scattered in code.
+
+## Function Design
+
+### Small and Focused
+
+Each function should do one thing. If you can name it with "and," it does too much:
+
+```javascript
+// Bad: does validation AND save AND send email
+function processUser(data) { ... }
+
+// Good: single responsibility
+function validateUser(data) { ... }
+function saveUser(user) { ... }
+function notifyUser(user) { ... }
+```
+
+### Few Arguments
+
+Ideal: 0–2 arguments. 3+ suggests the function needs a parameter object:
+
+```javascript
+// Bad
+function createUser(name, email, age, country, role) { ... }
+
+// Good
+function createUser(userData) { ... }
+```
+
+### No Side Effects
+
+Functions should not surprise callers. Hidden changes cause bugs:
+
+```javascript
+// Bad: modifies global, changes session
+function checkPassword(user, password) {
+  if (valid) session.authenticated = true;  // side effect!
+  return valid;
+}
+```
+
+## Avoiding Magic Numbers
+
+Replace unexplained literals with named constants:
+
+```javascript
+// Bad
+if (status === 3) { ... }
+setTimeout(callback, 86400000);
+
+// Good
+const ORDER_STATUS_SHIPPED = 3;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+if (status === ORDER_STATUS_SHIPPED) { ... }
+setTimeout(callback, MS_PER_DAY);
+```
+
+## DRY and YAGNI
+
+- **DRY (Don't Repeat Yourself):** Extract duplication into functions, constants, or modules.
+- **YAGNI (You Ain't Gonna Need It):** Don't add code for hypothetical future requirements.
+
+Balance: abstract when you see the *third* repetition, not the second.
+
+## Comments vs Self-Documenting Code
+
+Prefer clear code over comments:
+
+```javascript
+// Bad
+// Check if user is old enough
+if (u.a > 17) { ... }
+
+// Good
+const isAdult = user.age >= 18;
+if (isAdult) { ... }
+```
+
+**Good comments:** explain *why*, not *what*. Legal requirements, workarounds, non-obvious algorithms.
+
+## Code Smells
+
+| Smell | Fix |
+|-------|-----|
+| Long function | Extract smaller functions |
+| Long parameter list | Use object parameter |
+| Duplicate code | Extract and reuse |
+| Deep nesting | Early returns, extract functions |
+| Unclear names | Rename for clarity |
+
+## Before/After Refactoring
+
+**Before:**
+```javascript
+function calc(d, t) {
+  if (t === 0) return 0;
+  return d / t;
+}
+```
+
+**After:**
+```javascript
+function calculateSpeed(distanceInMeters, timeInSeconds) {
+  if (timeInSeconds === 0) return 0;
+  return distanceInMeters / timeInSeconds;
+}
+```
+
+Readability improved; intent is obvious.