{"id":51397532,"url":"https://github.com/stackql-registry/stackql-provider-utils","last_synced_at":"2026-07-04T03:35:40.711Z","repository":{"id":304140520,"uuid":"1017806165","full_name":"stackql-registry/stackql-provider-utils","owner":"stackql-registry","description":"Shared library of utilities for building and documenting StackQL providers from OpenAPI specifications.","archived":false,"fork":false,"pushed_at":"2026-04-13T00:17:14.000Z","size":4231,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T01:21:38.327Z","etag":null,"topics":["stackql","stackql-provider"],"latest_commit_sha":null,"homepage":"https://stackql.io/docs","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/stackql-registry.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-07-11T06:06:48.000Z","updated_at":"2026-02-19T23:23:05.000Z","dependencies_parsed_at":"2025-07-11T12:25:40.490Z","dependency_job_id":"cc138de8-1ba5-4c11-82ed-3ad06b6d0b39","html_url":"https://github.com/stackql-registry/stackql-provider-utils","commit_stats":null,"previous_names":["stackql/stackql-provider-utils","stackql-registry/stackql-provider-utils"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/stackql-registry/stackql-provider-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql-registry%2Fstackql-provider-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql-registry%2Fstackql-provider-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql-registry%2Fstackql-provider-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql-registry%2Fstackql-provider-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackql-registry","download_url":"https://codeload.github.com/stackql-registry/stackql-provider-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql-registry%2Fstackql-provider-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35109210,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"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":["stackql","stackql-provider"],"created_at":"2026-07-04T03:35:40.103Z","updated_at":"2026-07-04T03:35:40.705Z","avatar_url":"https://github.com/stackql-registry.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# StackQL Provider Utils\n\n![NPM Version](https://img.shields.io/npm/v/%40stackql%2Fprovider-utils)\n![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/stackql/stackql/total?style=plastic\u0026label=stackql%20downloads)\n\nA comprehensive toolkit for transforming OpenAPI specifications into StackQL providers. This library streamlines the process of parsing, mapping, validating, testing, and generating documentation for StackQL providers.\n\n## Table of Contents\n\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Directory Structure](#directory-structure)\n- [Provider Development Workflow](#provider-development-workflow)\n  - [`providerdev.split`](docs/split.md) - Divide a large OpenAPI specification into smaller, service-specific files\n  - [`providerdev.normalize`](docs/normalize.md) - Reshape split specs for relational consumption (flatten allOf, rename oneOf/anyOf, strip misplaced keywords, lower opaque objects)\n  - [`providerdev.analyze`](docs/analyze.md) - Examine split API specifications to generate mapping recommendations\n  - [`providerdev.generate`](docs/generate.md) - Create StackQL provider extensions from specifications and mappings\n  - [`docgen.generateDocs`](docs/docgen.md) - Generate comprehensive documentation for StackQL providers\n- [Contributing](#contributing)\n- [License](#license)\n- [Support](#support)\n\n## Prerequisites\n\n- Node.js \u003e= 20\n- `npm` or `yarn`\n- [`stackql`](https://stackql.io/docs/installing-stackql) for testing \n\n## Installation\n\nAdd `@stackql/provider-utils` to your `package.json`:\n\n```bash\nnpm install @stackql/provider-utils\n# or\nyarn add @stackql/provider-utils\n```\n\n## Consumer Setup: npm scripts\n\nThe package ships two CLI entry points: `provider-dev-utils` (for `split` / `normalize` / `analyze` / `generate`) and `docgen-utils` (for `generate-docs` / `generate-docs-v2`). Wrap them as npm scripts in your provider repo's `package.json` so every step of the workflow is a single `npm run \u003cstep\u003e` invocation:\n\n```json\n{\n  \"scripts\": {\n    \"split\":             \"node node_modules/@stackql/provider-utils/bin/provider-dev-utils.mjs split\",\n    \"normalize\":         \"node node_modules/@stackql/provider-utils/bin/provider-dev-utils.mjs normalize\",\n    \"generate-mappings\": \"node node_modules/@stackql/provider-utils/bin/provider-dev-utils.mjs analyze\",\n    \"generate-provider\": \"node node_modules/@stackql/provider-utils/bin/provider-dev-utils.mjs generate\",\n    \"generate-docs\":     \"node node_modules/@stackql/provider-utils/bin/docgen-utils.mjs generate-docs\"\n  }\n}\n```\n\nCall the bins through `node` (rather than relying on `node_modules/.bin/` shims) because npm does not always link `.bin` shims for `.mjs` files on Windows. Pass flags through with npm's `--` separator, e.g.:\n\n```bash\nnpm run normalize -- --api-dir provider-dev/source --verbose\n```\n\nJSON-valued flags (`--servers`, `--provider-config`, `--service-config`, `--skip-files`, `--svc-name-overrides`) accept either an inline JSON string or a path to a JSON file.\n\n### Full workflow example\n\n```bash\nnpm run split -- \\\n  --provider-name github \\\n  --api-doc provider-dev/downloaded/api.github.com.json \\\n  --svc-discriminator tag \\\n  --output-dir provider-dev/source \\\n  --overwrite\n\nnpm run normalize -- \\\n  --api-dir provider-dev/source \\\n  --verbose\n\nnpm run generate-mappings -- \\\n  --input-dir provider-dev/source \\\n  --output-dir provider-dev/config\n\nnpm run generate-provider -- \\\n  --provider-name github \\\n  --input-dir provider-dev/source \\\n  --output-dir provider-dev/openapi/src/github \\\n  --config-path provider-dev/config/all_services.csv \\\n  --servers '[{\"url\": \"https://api.github.com\"}]' \\\n  --provider-config '{\"auth\": {\"type\": \"basic\", \"username_var\": \"STACKQL_GITHUB_USERNAME\", \"password_var\": \"STACKQL_GITHUB_PASSWORD\"}}' \\\n  --overwrite\n\nnpm run generate-docs -- \\\n  --provider-name github \\\n  --provider-dir ./provider-dev/openapi/src/github/v00.00.00000 \\\n  --output-dir ./website \\\n  --provider-data-dir ./provider-dev/docgen/provider-data\n```\n\nOn `generate-provider`, `--provider-name` is accepted as an alias for `--provider-id` so the flag name is consistent with the other commands.\n\n## Directory Structure\n\nA typical project structure for the development of a `stackql` provider would be...\n\n```bash\n.\n├── bin # convinience scripts\n│   ├── ... \n├── provider-dev                            \n│   ├── config\n│   │   └── all_services.csv  # mappings generated or updated by the `providerdev.analyze` function, used by `providerdev.generate`\n│   ├── docgen\n│   │   └── provider-data  # provider metadata used by `docgen.generateDocs`\n│   │       ├── headerContent1.txt\n│   │       └── headerContent2.txt\n│   ├── downloaded # used to store the original spec for the provider\n│   │   └── management-minimal.yaml\n│   ├── openapi # output from `providerdev.generate`, this is the stackql provider\n│   │   └── src\n│   │       └── okta\n│   │           └── v00.00.00000\n│   │               ├── provider.yaml\n│   │               └── services\n│   │                   ├── agentpools.yaml\n│   │                   ├── ...\n│   ├── scripts # optional scripts for pre or post processing if required\n│   │   └── post_processing.sh\n│   └── source  # output from `providerdev.split` if used, this is the source used with the mappings to generate the provider\n│       ├── agentpools.yaml\n│       ├── ...\n└── website # docusaurus site\n    ├── docs # output from `docgen.generateDocs`\n    │   ├── ...\n```\n\n\u003e see [__stackql-provider-okta__](https://github.com/stackql/stackql-provider-okta) for a working example.\n\n## Provider Development Workflow\n\nThe library provides a streamlined workflow for creating StackQL providers from OpenAPI specifications:\n\n1. [`providerdev.split`](docs/split.md) - Divide a large OpenAPI specification into smaller, service-specific files\n2. [`providerdev.normalize`](docs/normalize.md) - Reshape split specs for relational consumption (flatten allOf, rename oneOf/anyOf, strip misplaced keywords, lower opaque objects)\n3. [`providerdev.analyze`](docs/analyze.md) - Examine split API specifications to generate mapping recommendations\n4. [`providerdev.generate`](docs/generate.md) - Create StackQL provider extensions from specifications and mappings\n5. [`docgen.generateDocs`](docs/docgen.md) - Generate comprehensive documentation for StackQL providers\n\n## Contributing\n\nContributions are welcome!\n\n## License\n\nMIT\n\n## Support\n\n- [StackQL Documentation](https://stackql.io/docs)\n- [GitHub Issues](https://github.com/stackql/stackql-provider-utils/issues)\n- [StackQL Community Slack](https://stackqlcommunity.slack.com/join/shared_invite/zt-1cbdq9s5v-CkY65IMAesCgFqjN6FU6hg)\n- [StackQL Discord](https://discord.com/invite/xVXZ9d5NxN)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql-registry%2Fstackql-provider-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackql-registry%2Fstackql-provider-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql-registry%2Fstackql-provider-utils/lists"}