{"id":15063091,"url":"https://github.com/system76/js-api","last_synced_at":"2025-07-02T12:36:20.920Z","repository":{"id":38983231,"uuid":"279417944","full_name":"system76/js-api","owner":"system76","description":"JavaScript fetch wrapper for Elixir Phoenix APIs","archived":false,"fork":false,"pushed_at":"2023-01-07T20:04:18.000Z","size":1115,"stargazers_count":5,"open_issues_count":11,"forks_count":1,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-06-10T19:06:51.267Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/system76.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2020-07-13T21:43:30.000Z","updated_at":"2021-11-08T08:50:50.000Z","dependencies_parsed_at":"2023-02-08T00:01:40.241Z","dependency_job_id":null,"html_url":"https://github.com/system76/js-api","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/system76/js-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/system76%2Fjs-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/system76%2Fjs-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/system76%2Fjs-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/system76%2Fjs-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/system76","download_url":"https://codeload.github.com/system76/js-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/system76%2Fjs-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263141254,"owners_count":23420040,"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","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":"2024-09-24T23:51:00.678Z","updated_at":"2025-07-02T12:36:20.866Z","avatar_url":"https://github.com/system76.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e@system76/js-api\u003c/h1\u003e\n  \u003ch3\u003eJavaScript fetch wrapper for Elixir Phoenix APIs\u003c/h3\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@system76/js-api/\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/@system76/js-api.svg\" alt=\"npm\"\u003e\n  \u003c/a\u003e\n\n  \u003ca href=\"https://github.com/system76/js-api/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/release-date/system76/js-api.svg\" alt=\"release\"\u003e\n  \u003c/a\u003e\n\n  \u003ca href=\"https://dependabot.com/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/dependabot-configured-success.svg\" alt=\"dependabot\"\u003e\n  \u003c/a\u003e\n\n  \u003ca href=\"https://standardjs.com\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/code_style-standard-brightgreen.svg\" alt=\"standard\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nThis package is a simple wrapper around\n[`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to make it\neasier to interact with [Elixir Phoenix](https://phoenixframework.org/) APIs. It\nis rather opinionated to System76 projects, but may be useful for other\nprojects.\n\nWhile this package can be used in any JS project, it is designed with Vue (and\nNuxt.JS) specifically in mind.\n\n## Using\n\n### Regular JS\n\n```\nnpm install --save @system76/js-api\n```\n\n```js\nimport { Client } from '@system76/js-api'\n\nconst api = () =\u003e new Client({\n  baseUrl: 'https://api-v2.system76.com',\n  token: () =\u003e 'testingtoken'\n})\n\nconst { data } = await api().get('/catalog/products').jsonApi()\n```\n\n### Nuxt\n\nAdd these fields to your `nuxt.config.js` file:\n\n```js\nexport default {\n  plugins: [\n    `~/plugins/api`\n  ]\n}\n```\n\nPut this in your `~/plugins/api.js`:\n\n```js\nimport { Client } from '@system76/js-api'\n\nexport default function (ctx, inject) {\n  const api = () =\u003e new Client({\n    baseUrl: 'https://api-v2.system76.com',\n    token: () =\u003e `Token ${ctx.store.getters.token}`\n  })\n\n  inject('api', () =\u003e api())\n}\n```\n\nThen you can use `$api` in the nuxt context. For instance, in a component you\ncan do:\n\n```js\nexport default {\n  asyncData: async ({ $api }) =\u003e ({\n    products: await $api().get('/catalog/products').jsonApi().flatten()\n  })\n}\n```\n\nor:\n\n```js\nexport default {\n  methods: {\n    async create () {\n      const { data: products } = await $api().get('/catalog/products')\n        .jsonApi()\n        .page(2)\n    }\n  }\n}\n```\n\n### Client\n\nThis is your main client used for making requests. All methods return the client\nagain, so it's easily chainable.\n\n```js\n// Adds an include statement to the request. Useful for JSON API endpoints\nclient.include('products.options.components')\n\n// Adds a header to the request\nclient.header('Accept', 'application/json')\n\n// Adds an authentication header\nclient.authentication('token abc123')\n\n// Adds a parameter to the URL\nclient.parameter('filter[status]', 'awesome')\n\n// Adds pagination page parameter\nclient.page(1)\n\n// Adds pagination page size parameter\nclient.size(100)\n\n// Adds a no cache or cache header to the request (defaults to true)\nclient.cache()\nclient.cache(false)\n\n// Adds JSON API headers and changes the request form a bit to match\nclient.jsonApi()\n\n// Adds body data to the request. Does not work with HEAD or GET requests. Gets\n// JSON.stringify-ed\nclient.body({ data: { attributes: { key: 'value' }}})\n\n// Sets the method and path for the request.\nclient.get('/products')\nclient.post('/products')\nclient.patch('/products')\nclient.put('/products')\nclient.delete('/products/2')\n\n// Makes the return value of the request _just_ the body data. This is similar\n// to doing `(await client.get()).body` but less verbose\nclient.flatten()\n```\n\n### ApiError\n\nThis is the error thrown if the response is not ok. It has a bunch of helpers\nto assist in parsing the error data.\n\n```js\n// Mapped for use in Nuxt. If the API returns a 500, your app returns a 500\nerror.status // 500\nerror.statusCode // 500\n\n// A simple array of error data found\nerror.errors // ['Not authorized']\nerror.errors // ['email has already been taken']\n\n// An object of validation errors from the server\nerror.fields.email // ['has already been taken']\nerror.fields.password // null\n```\n\n## Development\n\n1) Download the repository\n\n2) Run `npm ci`\n\n3) Start hacking\n\n4) Run `npm test` to make sure you didn't break anything\n\n5) Submit a PR!\n\n## Deployment\n\nTo [trigger a release](https://semantic-release.gitbook.io/semantic-release/#triggering-a-release),\npush a commit to the `master` branch in the\n[Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines)\nformat.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystem76%2Fjs-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsystem76%2Fjs-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsystem76%2Fjs-api/lists"}