{"id":30805571,"url":"https://github.com/aaronsb/jira-insights-api","last_synced_at":"2025-10-06T17:06:23.632Z","repository":{"id":283375375,"uuid":"951535630","full_name":"aaronsb/jira-insights-api","owner":"aaronsb","description":"A Node.js library that automatically generates a TypeScript client for the Atlassian JSM Insight API from the OpenAPI specification.","archived":false,"fork":false,"pushed_at":"2025-03-20T00:56:27.000Z","size":59,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-06T00:59:15.521Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/aaronsb.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}},"created_at":"2025-03-19T20:46:34.000Z","updated_at":"2025-07-04T15:33:58.000Z","dependencies_parsed_at":"2025-03-20T01:29:10.326Z","dependency_job_id":null,"html_url":"https://github.com/aaronsb/jira-insights-api","commit_stats":null,"previous_names":["aaronsb/jira-assets-api-client","aaronsb/jira-insights-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aaronsb/jira-insights-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fjira-insights-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fjira-insights-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fjira-insights-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fjira-insights-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronsb","download_url":"https://codeload.github.com/aaronsb/jira-insights-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fjira-insights-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278646783,"owners_count":26021512,"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-06T02:00:05.630Z","response_time":65,"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":[],"created_at":"2025-09-06T00:59:13.608Z","updated_at":"2025-10-06T17:06:23.617Z","avatar_url":"https://github.com/aaronsb.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Atlassian JSM Insight API\n\nA Node.js library that automatically generates a TypeScript client for the Atlassian JSM Insight API from the OpenAPI specification.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/aaronsb/jira-insights-api/main/assets/logo.png\" alt=\"Atlassian JSM Insight API Client\" width=\"200\" /\u003e\n\u003c/div\u003e\n\n## 📋 Table of Contents\n\n- [Features](#-features)\n- [Installation](#-installation)\n- [Quick Start](#-quick-start)\n- [Authentication](#-authentication)\n- [API Reference](#-api-reference)\n- [Examples](#-examples)\n- [Development](#-development)\n- [Documentation](#-documentation)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## ✨ Features\n\n- **Pre-Generated Client**: Includes a pre-generated client from the Atlassian JSM Insight API OpenAPI specification\n- **Runtime Ready**: Works reliably in all environments including Docker containers without runtime generation\n- **Type Safety**: Fully typed TypeScript client with accurate models and service definitions\n- **Modern**: Built with modern JavaScript practices and tools\n- **Flexible**: Configure via environment variables or programmatic options\n- **Comprehensive**: Access to all JSM Insight API endpoints and features\n- **ESM Compatible**: Works with both CommonJS and ES Modules projects\n- **Workspace Discovery**: Automatically discovers the workspace ID required for JSM Insight API\n\n## 📦 Installation\n\n```bash\nnpm install jira-insights-api\n```\n\n## 🚀 Quick Start\n\n```typescript\nimport { initAssetsApiClient } from 'jira-insights-api';\nimport dotenv from 'dotenv';\n\n// Load environment variables\ndotenv.config();\n\nasync function main() {\n  // Initialize the client\n  const insightClient = await initAssetsApiClient({\n    email: 'your-email@example.com',\n    apiToken: 'your-api-token-here',\n    instance: 'your-instance-name'\n  });\n\n  // Use the client to make API calls\n  const schemaList = await insightClient.DefaultService.schemaList();\n  console.log(`Found ${schemaList.values.length} schemas`);\n}\n\nmain().catch(console.error);\n```\n\n## 🔐 Authentication\n\nThe Atlassian JSM Insight API uses Basic authentication with email and API token. You can provide your credentials in one of two ways:\n\n### 1. Environment Variables\n\nCreate a `.env` file in your project root:\n\n```\nJIRA_EMAIL=your-email@example.com\nASSETS_API_TOKEN=your-api-token-here\nJIRA_INSTANCE=your-instance-name\n```\n\nThen load it in your code:\n\n```typescript\nimport dotenv from 'dotenv';\nimport { initAssetsApiClient } from 'jira-insights-api';\n\ndotenv.config();\nconst insightClient = await initAssetsApiClient();\n```\n\n### 2. Configuration Options\n\nPass authentication details directly to the client:\n\n```typescript\nconst insightClient = await initAssetsApiClient({\n  email: 'your-email@example.com',\n  apiToken: 'your-api-token-here',\n  instance: 'your-instance-name'\n});\n```\n\n### Getting an API Token\n\n1. Go to [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)\n2. Click \"Create API token\"\n3. Give your token a name and click \"Create\"\n4. Copy the token value (you won't be able to see it again)\n\n## 📚 API Reference\n\nThe client exposes the following services:\n\n### DefaultService\n\nThe main service for interacting with Atlassian JSM Insight API. Some key methods include:\n\n- `schemaList()`: Get all schemas\n- `objectTypeFindAll()`: Get all object types\n- `objectFindAll()`: Get all objects\n- `objectFindById(id)`: Get a specific object by ID\n- `objectCreate(data)`: Create a new object\n- `objectUpdate(id, data)`: Update an existing object\n- `objectDelete(id)`: Delete an object\n- `objectFindHistoryEntries(id)`: Get history for an object\n\nFor a complete list of available methods, initialize the client and explore the available services and methods:\n\n```typescript\nconst insightClient = await initAssetsApiClient();\nconsole.log(Object.keys(insightClient.DefaultService));\n```\n\n## 📝 Examples\n\n### Working with Objects\n\n```typescript\n// Get all objects of a specific type\nconst objects = await insightClient.DefaultService.objectFindAll({\n  objectTypeId: '1',\n  includeAttributes: true\n});\n\n// Get a specific object\nconst object = await insightClient.DefaultService.objectFindById({\n  id: '123456789'\n});\n\n// Create a new object\nconst newObject = await insightClient.DefaultService.objectCreate({\n  requestBody: {\n    name: 'New Asset',\n    objectTypeId: '1',\n    attributes: {\n      description: 'A new asset created via API'\n    }\n  }\n});\n\n// Update an object\nawait insightClient.DefaultService.objectUpdate({\n  id: '123456789',\n  requestBody: {\n    name: 'Updated Asset Name'\n  }\n});\n\n// Delete an object\nawait insightClient.DefaultService.objectDelete({\n  id: '123456789'\n});\n```\n\n### Pagination\n\n```typescript\nasync function getAllObjects(objectTypeId) {\n  const allObjects = [];\n  let page = 1;\n  let hasMore = true;\n\n  while (hasMore) {\n    const response = await insightClient.DefaultService.objectFindAll({\n      objectTypeId,\n      includeAttributes: true,\n      page,\n      resultsPerPage: 50\n    });\n\n    if (response \u0026\u0026 response.length \u003e 0) {\n      allObjects.push(...response);\n      console.log(`Retrieved page ${page} with ${response.length} objects (total: ${allObjects.length})`);\n      page++;\n    } else {\n      hasMore = false;\n    }\n  }\n\n  return allObjects;\n}\n\nconst allObjects = await getAllObjects('1'); // Replace with an actual object type ID\n```\n\n### Error Handling\n\n```typescript\ntry {\n  const object = await insightClient.DefaultService.objectFindById({\n    id: 'non-existent-id'\n  });\n} catch (error) {\n  if (error.status === 404) {\n    console.error('Object not found');\n  } else {\n    console.error('API error:', error.message);\n  }\n}\n```\n\nSee the [examples](./examples) directory for more usage examples.\n\n## 🛠️ Development\n\n### Project Structure\n\n```\njira-insights-api/\n├── src/\n│   ├── downloadAssetsApiSpec.ts   # Downloads the OpenAPI spec\n│   ├── generateAssetsApiClient.ts # Generates the TypeScript client\n│   ├── fixGeneratedCode.ts        # Fixes issues in generated code\n│   ├── prebuild.ts                # Pre-build script for client generation\n│   ├── index.ts                   # Main entry point\n│   └── generated/                 # Generated API client code (development only)\n├── examples/\n│   ├── basic-usage.ts             # Basic usage example\n│   └── advanced-usage.ts          # Advanced usage example\n├── docs/\n│   ├── API.md                     # API reference documentation\n│   └── GETTING_STARTED.md         # Getting started guide\n├── dist/                          # Compiled JavaScript\n│   └── generated/                 # Pre-generated client code included in the package\n```\n\n### Pre-Generated Client\n\nStarting with version 2.1.1, this package includes a pre-generated client in the published package. This means:\n\n1. No runtime generation is required when using the package\n2. Works reliably in all environments, including Docker containers\n3. Faster initialization and better performance\n4. Consistent behavior across different environments\n\nThe client is generated during the package build process and included in the published package.\n\n### Available Scripts\n\n- `npm run download`: Download the latest Atlassian JSM Insight API specification\n- `npm run generate`: Generate the TypeScript client from the specification (runs fix automatically after)\n- `npm run fix`: Fix any issues in the generated code\n- `npm run build`: Build the project (includes pre-generating the client)\n- `npm run clean`: Clean the build directory\n- `npm run clean:generated`: Remove all generated files (API spec and generated code)\n- `npm run reset`: Clean both build and generated files\n- `npm run example`: Run the basic usage example\n- `npm run example:advanced`: Run the advanced usage example\n\n### Continuous Integration\n\nThis project uses GitHub Actions for continuous integration and deployment:\n\n- **Automated Publishing**: The package is automatically published to npm when:\n  - Changes are pushed to the `main` branch that modify `package.json`\n  - A new GitHub Release is created\n  - The workflow is manually triggered\n\nThe CI pipeline:\n1. Downloads the latest Atlassian JSM Insight API specification\n2. Generates the TypeScript client during the build process\n3. Builds the package with the pre-generated client included\n4. Publishes to npm with public access\n\nTo set up automated publishing in your fork:\n1. Create an npm access token with publish permissions\n2. Add the token as a GitHub repository secret named `NPM_TOKEN`\n\n### Configuration Options\n\n```typescript\ninterface AssetsApiClientOptions {\n  // Email address for authentication\n  email?: string;\n  \n  // API token for authentication\n  apiToken?: string;\n  \n  // Jira instance name (e.g., 'your-instance' from 'your-instance.atlassian.net')\n  instance?: string;\n  \n  // Workspace ID for JSM Insight API (if not provided, it will be discovered automatically)\n  workspaceId?: string;\n  \n  // Legacy base URL (not recommended for new projects)\n  baseUrl?: string;\n  \n  // Path to the API specification file\n  specFile?: string;\n  \n  // Directory to output the generated code\n  outputDir?: string;\n  \n  // Whether to regenerate the client code\n  regenerate?: boolean;\n}\n```\n\n## 📖 Documentation\n\nComprehensive documentation is available in the `docs` directory:\n\n- [Getting Started Guide](./docs/GETTING_STARTED.md) - A step-by-step guide to get up and running\n- [API Reference](./docs/API.md) - Detailed information about all available methods and options\n\nAdditional resources:\n\n- [Examples](./examples) - Example scripts demonstrating various use cases\n- [Atlassian JSM Insight API Documentation](https://developer.atlassian.com/cloud/jira/service-desk/rest/intro/) - Official Atlassian documentation\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fjira-insights-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronsb%2Fjira-insights-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fjira-insights-api/lists"}