{"id":38404320,"url":"https://github.com/graphlit/graphlit-portal-client-typescript","last_synced_at":"2026-01-17T04:00:07.843Z","repository":{"id":322723656,"uuid":"1088540380","full_name":"graphlit/graphlit-portal-client-typescript","owner":"graphlit","description":"TypeScript client for the Graphlit Platform Control Plane","archived":false,"fork":false,"pushed_at":"2025-12-21T02:55:05.000Z","size":128,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-22T23:32:10.932Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/graphlit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-11-03T05:31:07.000Z","updated_at":"2025-12-21T02:55:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/graphlit/graphlit-portal-client-typescript","commit_stats":null,"previous_names":["graphlit/graphlit-portal-client-typescript"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/graphlit/graphlit-portal-client-typescript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphlit%2Fgraphlit-portal-client-typescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphlit%2Fgraphlit-portal-client-typescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphlit%2Fgraphlit-portal-client-typescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphlit%2Fgraphlit-portal-client-typescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/graphlit","download_url":"https://codeload.github.com/graphlit/graphlit-portal-client-typescript/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphlit%2Fgraphlit-portal-client-typescript/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28494112,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T02:39:23.645Z","status":"ssl_error","status_checked_at":"2026-01-17T02:34:19.649Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2026-01-17T04:00:07.357Z","updated_at":"2026-01-17T04:00:07.678Z","avatar_url":"https://github.com/graphlit.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Graphlit Portal Client SDK\n\n[![npm version](https://badge.fury.io/js/graphlit-portal-client.svg)](https://badge.fury.io/js/graphlit-portal-client)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nThe official TypeScript/JavaScript SDK for the [Graphlit Platform](https://www.graphlit.com) Control Plane API - programmatically manage your infrastructure, projects, and organization.\n\n## 🚀 What is the Graphlit Portal Client?\n\nThe Portal Client SDK enables **infrastructure-as-code** for Graphlit - automate project management, billing, and organization settings through a clean TypeScript/JavaScript API.\n\n**Use Cases:**\n\n- **DevOps Automation** - Create/destroy projects in CI/CD pipelines\n- **Multi-tenant Apps** - Provision projects per customer\n- **Infrastructure Management** - Manage environments, billing, and quotas\n- **Testing** - Spin up ephemeral test projects\n- **Monitoring** - Query project status and usage\n\n## ✨ Key Features\n\n- 🏗️ **Project Management** - Full CRUD operations for Graphlit projects\n- 💳 **Subscription Control** - Upgrade/downgrade project tiers programmatically\n- 🔐 **API Key Auth** - Secure organization-level access with API keys\n- 🌍 **Multi-Environment** - Switch between production and development APIs\n- 📘 **Full TypeScript** - Auto-generated types from GraphQL schema\n- 🔄 **GraphQL Native** - Built on Apollo Client for reliability\n\n## 📋 Table of Contents\n\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Getting API Keys](#getting-api-keys)\n- [Configuration](#configuration)\n- [Basic Examples](#basic-examples)\n- [API Reference](#api-reference)\n  - [Project Operations](#project-operations)\n  - [Subscription Management](#subscription-management)\n- [API Endpoint](#api-endpoint)\n- [Error Handling](#error-handling)\n- [TypeScript Support](#typescript-support)\n- [Related SDKs](#related-sdks)\n- [Development](#development)\n- [Support](#support)\n\n## Quick Start\n\nGet started in 2 minutes:\n\n```bash\n# Install the SDK\nnpm install graphlit-portal-client\n\n# Set your credentials (from https://portal.graphlit.dev/api-keys)\nexport GRAPHLIT_API_KEY=glk_live_your_key_here\nexport GRAPHLIT_ORGANIZATION_ID=your_org_guid_here\n```\n\n```typescript\nimport { GraphlitPortalClient } from \"graphlit-portal-client\";\n\n// Initialize client (uses env vars automatically)\nconst client = new GraphlitPortalClient();\n\n// Create a project (platform and region are automatically configured)\nconst project = await client.createProject({\n  name: \"My Production App\",\n  description: \"Production environment\",\n});\n\nconsole.log(`Created project: ${project.createProject?.name}`);\nconsole.log(`Project ID: ${project.createProject?.id}`);\nconsole.log(`Data API: ${project.createProject?.uri}`);\n```\n\n## Installation\n\n```bash\nnpm install graphlit-portal-client\n```\n\n**Requirements:**\n\n- Node.js 18.0 or higher\n- TypeScript 5.0 or higher (for TypeScript projects)\n\n## Getting API Keys\n\nTo use this SDK, you need an organization API key:\n\n1. Go to [Graphlit Portal](https://portal.graphlit.dev)\n2. Navigate to your organization → **API Keys**\n3. Click **Create API Key**\n4. Give it a name (e.g., \"CI/CD Pipeline\", \"Production Server\")\n5. **Copy the key immediately** - it's shown only once!\n6. Store it securely (environment variables, secrets manager, etc.)\n\n**⚠️ Security Note:** API keys have full access to your organization. Treat them like passwords:\n\n- Never commit them to version control\n- Use environment variables or secret management\n- Rotate keys periodically\n- Revoke immediately if compromised\n\n## Configuration\n\n### Option 1: Environment Variables (Recommended)\n\nCreate a `.env` file:\n\n```env\n# Required\nGRAPHLIT_API_KEY=glk_live_your_key_here\nGRAPHLIT_ORGANIZATION_ID=your_org_guid_here\n```\n\n```typescript\nimport { GraphlitPortalClient } from \"graphlit-portal-client\";\n\nconst client = new GraphlitPortalClient();\n// Automatically uses environment variables\n```\n\n### Option 2: Explicit Configuration\n\n```typescript\nimport { GraphlitPortalClient } from \"graphlit-portal-client\";\n\nconst client = new GraphlitPortalClient({\n  apiKey: \"glk_live_...\",\n  organizationId: \"your-org-guid\",\n});\n```\n\n### Option 3: Legacy Constructor (Backward Compatible)\n\n```typescript\nconst client = new GraphlitPortalClient(\n  \"glk_live_...\", // apiKey\n  \"your-org-guid\", // organizationId\n  \"https://portal.graphlit.io/api/v1/graphql\", // portalUri (optional)\n);\n```\n\n## Basic Examples\n\n### Creating Your First Project\n\n```typescript\nimport { GraphlitPortalClient } from \"graphlit-portal-client\";\n\nconst client = new GraphlitPortalClient();\n\nconst project = await client.createProject({\n  name: \"Analytics Platform\",\n  description: \"Customer analytics with AI\",\n});\n\nconsole.log(\"Project created:\", project.createProject);\nconsole.log(\"Platform:\", project.createProject?.platform); // Azure\nconsole.log(\"Region:\", project.createProject?.region); // southcentralus\n```\n\n### Listing All Projects\n\n```typescript\n// Query all projects\nconst results = await client.queryProjects();\n\nresults.projects?.results?.forEach((p) =\u003e {\n  console.log(`${p.name} (${p.id})`);\n  console.log(`  Platform: ${p.platform}`);\n  console.log(`  Region: ${p.region}`);\n  console.log(`  Data API: ${p.uri}`);\n});\n\n// With filtering\nconst filtered = await client.queryProjects({\n  ids: [\"project-id-1\", \"project-id-2\"],\n});\n```\n\n### Getting Project Details\n\n```typescript\nconst project = await client.getProject(\"project-id\");\n\nconsole.log(\"Project:\", project.project?.name);\nconsole.log(\"Created:\", project.project?.creationDate);\nconsole.log(\"Platform:\", project.project?.platform);\nconsole.log(\"State:\", project.project?.state);\n\n// Check quota usage\nif (project.project?.quota) {\n  console.log(\"Credits:\", project.project.quota.credits);\n}\n```\n\n### Updating a Project\n\n```typescript\nawait client.updateProject({\n  id: \"project-id\",\n  name: \"Updated Project Name\",\n  description: \"New description\",\n});\n\nconsole.log(\"Project updated successfully\");\n```\n\n### Upgrading Project Subscription\n\n```typescript\n// Upgrade to Enterprise tier\nawait client.updateProjectSubscription(\"project-id\", \"prod_enterprise_monthly\");\n\nconsole.log(\"Subscription upgraded to Enterprise\");\n```\n\n### Deleting a Project\n\n```typescript\nawait client.deleteProject(\"project-id\");\nconsole.log(\"Project deleted\");\n```\n\n## API Reference\n\n### Project Operations\n\n#### `createProject(input: CreateProjectInput): Promise\u003cCreateProjectMutation\u003e`\n\nCreate a new Graphlit project. Projects are automatically provisioned on Azure in the South Central US region.\n\n**Parameters:**\n\n- `name` (string, required) - Project name\n- `description` (string, optional) - Project description\n\n**Returns:** Created project with `id`, `name`, `uri`, `platform` (Azure), `region` (southcentralus), etc.\n\n**Example:**\n\n```typescript\nconst project = await client.createProject({\n  name: \"Production App\",\n  description: \"Main production environment\",\n});\n\nconsole.log(`Project created: ${project.createProject?.id}`);\nconsole.log(`Data Plane API: ${project.createProject?.uri}`);\n```\n\n---\n\n#### `updateProject(input: ProjectUpdateInput): Promise\u003cUpdateProjectMutation\u003e`\n\nUpdate an existing project's metadata.\n\n**Parameters:**\n\n- `id` (string, required) - Project ID\n- `name` (string, optional) - New project name\n- `description` (string, optional) - New description\n\n**Example:**\n\n```typescript\nawait client.updateProject({\n  id: \"proj_abc123\",\n  name: \"Updated Name\",\n});\n```\n\n---\n\n#### `deleteProject(id: string): Promise\u003cDeleteProjectMutation\u003e`\n\nPermanently delete a project and all its data.\n\n**⚠️ Warning:** This action is irreversible. All environments, data, and configurations will be deleted.\n\n**Parameters:**\n\n- `id` (string, required) - Project ID to delete\n\n**Example:**\n\n```typescript\nawait client.deleteProject(\"proj_abc123\");\n```\n\n---\n\n#### `getProject(id: string): Promise\u003cGetProjectQuery\u003e`\n\nRetrieve detailed information about a specific project.\n\n**Parameters:**\n\n- `id` (string, required) - Project ID\n\n**Returns:** Project details including quota, subscription, and configuration\n\n**Example:**\n\n```typescript\nconst result = await client.getProject(\"proj_abc123\");\nconsole.log(result.project?.name);\n```\n\n---\n\n#### `queryProjects(filter?: ProjectFilter): Promise\u003cQueryProjectsQuery\u003e`\n\nQuery projects with optional filtering.\n\n**Parameters:**\n\n- `filter` (ProjectFilter, optional) - Filter criteria\n  - `ids` (string[]) - Filter by specific project IDs\n  - Additional filters available in schema\n\n**Returns:** Array of projects matching the filter\n\n**Example:**\n\n```typescript\nconst results = await client.queryProjects({\n  ids: [\"proj_1\", \"proj_2\"],\n});\n```\n\n---\n\n### Subscription Management\n\n#### `updateProjectSubscription(id: string, productIdentifier: string): Promise\u003cUpdateProjectSubscriptionMutation\u003e`\n\nUpgrade or change a project's subscription tier.\n\n**Parameters:**\n\n- `id` (string, required) - Project ID\n- `productIdentifier` (string, required) - Stripe product identifier (e.g., `prod_starter_monthly`, `prod_enterprise_yearly`)\n\n**Example:**\n\n```typescript\nawait client.updateProjectSubscription(\n  \"proj_abc123\",\n  \"prod_enterprise_monthly\",\n);\n```\n\n---\n\n## API Endpoint\n\nThe SDK connects to the Graphlit Portal API at:\n\n```\nhttps://portal.graphlit.io/api/v1/graphql\n```\n\nThis is configured by default. You typically don't need to specify the `portalUri` unless you have a custom deployment.\n\n## Error Handling\n\nHandle errors gracefully in your applications:\n\n```typescript\nimport { GraphlitPortalClient } from \"graphlit-portal-client\";\n\nconst client = new GraphlitPortalClient();\n\ntry {\n  const project = await client.createProject({\n    name: \"New Project\",\n    description: \"My new project\",\n  });\n\n  console.log(\"Success:\", project.createProject?.id);\n} catch (error) {\n  if (error instanceof Error) {\n    console.error(\"Failed to create project:\", error.message);\n\n    // Check for specific error types\n    if (error.message.includes(\"quota\")) {\n      console.error(\"Project quota exceeded\");\n    } else if (error.message.includes(\"authentication\")) {\n      console.error(\"Invalid API key or organization ID\");\n    }\n  }\n}\n```\n\n### Common Error Scenarios\n\n| Error                         | Cause                                | Solution                                        |\n| ----------------------------- | ------------------------------------ | ----------------------------------------------- |\n| `API key is required`         | Missing `GRAPHLIT_API_KEY`           | Set environment variable or pass to constructor |\n| `Organization ID is required` | Missing `GRAPHLIT_ORGANIZATION_ID`   | Set environment variable or pass to constructor |\n| `Failed to create project`    | Invalid parameters or quota exceeded | Check parameters and organization limits        |\n| `Authentication failed`       | Invalid API key                      | Generate new API key in portal                  |\n| `Project not found`           | Invalid project ID                   | Verify project ID exists                        |\n\n## TypeScript Support\n\nThe SDK is built with TypeScript and provides full type safety:\n\n```typescript\nimport {\n  GraphlitPortalClient,\n  CreateProjectInput,\n  Project,\n} from \"graphlit-portal-client\";\n\nconst client = new GraphlitPortalClient();\n\n// Type-safe project creation\nconst input: CreateProjectInput = {\n  name: \"My Project\",\n  description: \"Description\",\n};\n\nconst result = await client.createProject(input);\n\n// Type-safe access to result\nconst project: Project | null | undefined = result.createProject;\nif (project) {\n  console.log(project.id); // TypeScript knows these properties exist\n  console.log(project.name);\n  console.log(project.uri);\n  console.log(project.platform); // Azure\n  console.log(project.region); // southcentralus\n}\n```\n\n### Available Types\n\nAll types are auto-generated from the GraphQL schema:\n\n```typescript\nimport type {\n  // Input types\n  CreateProjectInput,\n  ProjectUpdateInput,\n  ProjectFilter,\n\n  // Return types\n  Project,\n  ProjectQuota,\n  Subscription,\n\n  // Enums\n  EntityState,\n  SubscriptionStatus,\n\n  // Mutation results\n  CreateProjectMutation,\n  UpdateProjectMutation,\n  DeleteProjectMutation,\n\n  // Query results\n  GetProjectQuery,\n  QueryProjectsQuery,\n} from \"graphlit-portal-client\";\n```\n\n## Related SDKs\n\nThe Graphlit Platform has two complementary SDKs:\n\n| SDK                                                                    | Purpose                   | Auth                 | Scope             |\n| ---------------------------------------------------------------------- | ------------------------- | -------------------- | ----------------- |\n| **`graphlit-portal-client`** (this SDK)                                | Infrastructure management | Organization API key | Organization-wide |\n| **[`graphlit-client`](https://www.npmjs.com/package/graphlit-client)** | Data operations \u0026 AI      | Project JWT          | Single project    |\n\n### Typical Workflow\n\n1. **Use Portal Client** to provision infrastructure:\n\n   ```typescript\n   import { GraphlitPortalClient } from 'graphlit-portal-client';\n\n   const portal = new GraphlitPortalClient();\n   const project = await portal.createProject({ ... });\n   ```\n\n2. **Use Data Client** for application operations:\n\n   ```typescript\n   import { Graphlit } from \"graphlit-client\";\n\n   const client = new Graphlit({\n     organizationId: process.env.GRAPHLIT_ORGANIZATION_ID,\n     environmentId: project.productionEnvId,\n     jwtSecret: project.jwtSecret,\n   });\n\n   // Now ingest content, chat with AI, etc.\n   await client.ingestUri({ uri: \"https://example.com/doc.pdf\" });\n   ```\n\n## Development\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/graphlit/graphlit-portal-client-typescript.git\ncd graphlit-portal-client-typescript\n\n# Install dependencies\nnpm install\n\n# Generate GraphQL types from schema\nnpm run generate\n\n# Build the SDK\nnpm run build\n\n# Format code\nnpm run format\n```\n\n### Project Structure\n\n```\ngraphlit-portal-client-typescript/\n├── src/\n│   ├── client.ts                 # Main SDK client\n│   ├── documents/                # GraphQL operations\n│   │   └── project/\n│   │       ├── createProject.graphql\n│   │       ├── updateProject.graphql\n│   │       └── ...\n│   └── generated/                # Auto-generated types\n│       ├── graphql-types.ts\n│       └── graphql-documents.ts\n├── examples/\n│   └── basic-usage.ts           # Usage examples\n├── dist/                        # Compiled output\n├── package.json\n├── codegen.yml                  # GraphQL code generation config\n└── tsconfig.json\n```\n\n### Running Examples\n\n```bash\n# Set up environment\ncp examples/.env.example .env\n# Edit .env with your credentials\n\n# Run example\nnpx ts-node examples/basic-usage.ts\n```\n\n## Support\n\n### Documentation\n\n- 📚 [Graphlit Documentation](https://docs.graphlit.io)\n- 🔐 [API Keys Guide](https://docs.graphlit.io/api-keys)\n- 🏗️ [Control Plane API Reference](https://docs.graphlit.io/control-plane-api)\n\n### Community \u0026 Help\n\n- 💬 [Discord Community](https://discord.gg/graphlit) - Get help from the team and community\n- 🐛 [GitHub Issues](https://github.com/graphlit/graphlit-portal-client-typescript/issues) - Report bugs or request features\n- 📧 [Email Support](mailto:support@graphlit.com) - Enterprise support\n\n### Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details\n\n---\n\n**Built with ❤️ by [Unstruk Data Inc.](https://www.graphlit.com)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphlit%2Fgraphlit-portal-client-typescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraphlit%2Fgraphlit-portal-client-typescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphlit%2Fgraphlit-portal-client-typescript/lists"}