{"id":32143383,"url":"https://github.com/gah-code/contentful-context-toolkit","last_synced_at":"2026-05-08T05:10:22.927Z","repository":{"id":319393340,"uuid":"1078088905","full_name":"gah-code/contentful-context-toolkit","owner":"gah-code","description":"Lightweight toolkit for Contentful GraphQL introspection, mapping, and content snapshotting.","archived":false,"fork":false,"pushed_at":"2025-10-18T02:24:14.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-19T01:22:09.912Z","etag":null,"topics":["contentful","graphql","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gah-code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-17T07:34:35.000Z","updated_at":"2025-10-18T02:24:18.000Z","dependencies_parsed_at":"2025-10-19T01:22:21.002Z","dependency_job_id":"5ce46b23-6df9-4bed-a6b8-5d863c781f45","html_url":"https://github.com/gah-code/contentful-context-toolkit","commit_stats":null,"previous_names":["gah-code/contentful-context-toolkit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/gah-code/contentful-context-toolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gah-code%2Fcontentful-context-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gah-code%2Fcontentful-context-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gah-code%2Fcontentful-context-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gah-code%2Fcontentful-context-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gah-code","download_url":"https://codeload.github.com/gah-code/contentful-context-toolkit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gah-code%2Fcontentful-context-toolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280225809,"owners_count":26293888,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["contentful","graphql","nodejs"],"created_at":"2025-10-21T07:59:51.647Z","updated_at":"2026-05-08T05:10:22.911Z","avatar_url":"https://github.com/gah-code.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# 🧩 Contentful Context Toolkit\n\n![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)\n![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)\n[![Build Status](https://github.com/gah-code/contentful-context-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/gah-code/contentful-context-toolkit/actions)\n![Last Commit](https://img.shields.io/github/last-commit/gah-code/contentful-context-toolkit.svg)\n![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)\n![Made with](https://img.shields.io/badge/made%20with-Contentful-orange)\n\nA lightweight Node.js utility for introspecting your Contentful GraphQL API, extracting the content type map, fetching live content snapshots, and generating field-aware Markdown schema documentation.\n\n---\n\n## 🚀 Quick Start\n\n### 1. Setup\n\n```bash\ngit clone \u003cyour-repo-url\u003e\ncd contentful-context-toolkit\nnpm install\n````\n\nAdd your credentials to `.env`:\n\n```\nCONTENTFUL_SPACE_ID=your_space_id\nCONTENTFUL_ENVIRONMENT=master\nCONTENTFUL_CDA_TOKEN=your_content_delivery_token\n```\n\n*(Do not commit this file — it’s already excluded via `.gitignore`.)*\n\n---\n\n### 2. Run the Toolkit\n\n#### Individual commands\n\n```bash\nnpm run introspect      # Fetch full schema from Contentful (with field types)\nnpm run generate-map    # Generate content type map\nnpm run fetch-content   # Fetch sample content entries\nnpm run docs            # Build Markdown schema documentation\n```\n\n#### Full workflow\n\n```bash\nnpm run context\n```\n\nRuns introspection → map → snapshot.\n\n#### Complete pipeline (with docs)\n\n```bash\nnpm run context-docs\n```\n\nRuns the entire workflow plus documentation generation.\n\n---\n\n## 💻 CLI Command Aliases\n\nYou can now use the built-in CLI for simpler, friendlier commands:\n\n```bash\nnpm run context \u003ccommand\u003e\n```\n\nAvailable commands:\n\n| Command      | Description                         |\n| ------------ | ----------------------------------- |\n| `introspect` | Fetch schema from Contentful        |\n| `map`        | Generate content type map           |\n| `fetch`      | Fetch sample content entries        |\n| `docs`       | Build Markdown schema documentation |\n| `all`        | Run full `context-docs` pipeline    |\n\nExamples:\n\n```bash\nnpm run context introspect\nnpm run context fetch\nnpm run context all\n```\n\nIf you run `npm run context` with no arguments, it will display a help menu.\n\n---\n\n### 🧾 Outputs\n\nAll generated files appear in `src/data/` and `docs/`:\n\n| File                             | Description                                             |\n| -------------------------------- | ------------------------------------------------------- |\n| `src/data/schema.json`           | Full GraphQL schema (includes field types)              |\n| `src/data/content_map.json`      | Simplified type → field map                             |\n| `src/data/content_snapshot.json` | Sample content data from your space                     |\n| `docs/schema_docs.md`            | Markdown schema documentation with accurate field types |\n\n---\n\n### ✅ Example Output\n\n```markdown\n## BlogPost\n**Entries fetched:** 3\n\n**Fields:**\n- _id: ID  \n- title: String  \n- slug: String  \n- excerpt: String  \n- body: JSON  \n- author: Entry  \n- image: Asset  \n- seoTitle: String  \n- seoDescription: String  \n- date: DateTime  \n```\n\n---\n\n## 🧠 Project Overview\n\n| Folder        | Purpose                                                    |\n| ------------- | ---------------------------------------------------------- |\n| `src/config`  | Stores API endpoints and environment configuration         |\n| `src/schema`  | Handles schema introspection and content type extraction   |\n| `src/queries` | Builds and runs auto-generated GraphQL queries             |\n| `src/utils`   | Shared helpers like GraphQL client and logging             |\n| `src/docs`    | Generates Markdown schema documentation                    |\n| `src/cli`     | Provides CLI command aliases (`npm run context \u003ccommand\u003e`) |\n| `src/data`    | Stores generated outputs (schema, map, snapshot)           |\n| `tests/`      | (optional) Add unit or integration tests later             |\n\n---\n\n## 🧭 Update Tracker\n\n| Date       | Update                | Notes                                                       |\n| ---------- | --------------------- | ----------------------------------------------------------- |\n| 2025-10-16 | Initial scaffold      | Schema → map → snapshot workflow                            |\n| 2025-10-17 | Enriched fetch        | Added filtered content queries and folder auto-creation     |\n| 2025-10-17 | Docs generator        | Added Markdown documentation generator (`npm run docs`)     |\n| 2025-10-17 | Unified pipeline      | Added `context-docs` full sync command                      |\n| 2025-10-18 | Field types resolved  | Updated introspection query to capture accurate field types |\n| 2025-10-19 | CLI aliases added     | Introduced `npm run context \u003ccommand\u003e` subcommands          |\n| *TBD*      | Relationship mapping  | Map cross-type links and references                         |\n| *TBD*      | Visualization support | Export schema for GraphQL Voyager                           |\n| *TBD*      | Type generation       | Add GraphQL Codegen for TypeScript models                   |\n\n---\n\n## 🧱 Task Backlog\n\n* [x] Add GraphQL schema documentation generator\n* [x] Combine full pipeline (`context-docs`)\n* [x] Fix field type resolution in documentation\n* [x] Add CLI command aliases (`context introspect`, `context fetch`)\n* [ ] Add GraphQL Voyager visualization output\n* [ ] Implement relationship mapping between content types\n* [ ] Implement retry + error handling for API requests\n* [ ] Add watch mode to auto-update content_map.json on schema change\n* [ ] Integrate TypeScript types (future expansion)\n\n---\n\n## 🪄 Notes\n\nThis toolkit is intentionally minimal but fully operational.\nYou can extend it to:\n\n* Generate React/Gatsby components automatically from Contentful models\n* Integrate with CI/CD to track schema and documentation changes\n* Visualize your model structure with GraphQL Voyager\n* Export data to other formats (Markdown, JSON, HTML)\n\nStay modular. Keep your data clear. And always know your content universe.\n\n---\n\n## 🔐 Security \u0026 Best Practices\n\n* **Never commit `.env`** — use `.env.example` for shared configs.\n* **Keep your CDA token private** — treat it like a password.\n* Run `npm run context all` before each commit to ensure your docs stay up-to-date.\n* Generated files in `src/data/` are reproducible — do not version them.\n\n---\n\n## 🧩 License\n\nMIT © 2025\nMaintained by **Contentful Context Toolkit contributors**\n\n---\n\nThis version:\n\n* ✅ Documents the new CLI commands clearly.  \n* ✅ Keeps global install instructions (Step 4) out for now.  \n* ✅ Updates the tracker to mark CLI aliases as complete.  \n* ✅ Keeps everything else current and consistent with your codebase.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgah-code%2Fcontentful-context-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgah-code%2Fcontentful-context-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgah-code%2Fcontentful-context-toolkit/lists"}