{"id":18683110,"url":"https://github.com/foxy/foxy-sdk","last_synced_at":"2026-01-26T17:10:38.297Z","repository":{"id":40361274,"uuid":"298083167","full_name":"Foxy/foxy-sdk","owner":"Foxy","description":"Universal SDK for a full server-side and a limited in-browser access to Foxy hAPI.","archived":false,"fork":false,"pushed_at":"2025-02-26T18:01:21.000Z","size":1258,"stargazers_count":5,"open_issues_count":4,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-12T02:07:29.871Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://sdk.foxy.dev","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/Foxy.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-23T20:12:15.000Z","updated_at":"2025-02-12T23:33:01.000Z","dependencies_parsed_at":"2024-01-17T19:35:12.801Z","dependency_job_id":"8af69c76-ee14-41db-ba75-66b17f799a66","html_url":"https://github.com/Foxy/foxy-sdk","commit_stats":null,"previous_names":[],"tags_count":60,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxy%2Ffoxy-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxy%2Ffoxy-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxy%2Ffoxy-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Foxy%2Ffoxy-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Foxy","download_url":"https://codeload.github.com/Foxy/foxy-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248517152,"owners_count":21117397,"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-11-07T10:13:46.442Z","updated_at":"2026-01-26T17:10:38.267Z","avatar_url":"https://github.com/Foxy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Foxy SDK 🦊🧱\n\nUniversal SDK for a full server-side and a limited in-browser access to Foxy hAPI.\n\n## Setup\n\nInstall the package:\n\n```bash\nnpm i @foxy.io/sdk\n```\n\nThen import using CommonJS (Node 10-12):\n\n```js\nconst FoxySDK = require('@foxy.io/sdk');\n```\n\nor ES Modules (Node 13+, TypeScript, browsers):\n\n```js\nimport * as FoxySDK from '@foxy.io/sdk';\n```\n\n## Getting started\n\nOur SDK consists of 3 main parts available via the main file:\n\n1. **Backend** is for building Node.JS apps that connect to hAPI directly from a safe **server-side** environment. Apart from the API client, you'll also find a number of useful utilities for HMAC signing, removing sensitive info from responses and webhook verification under this export alias.\n2. **Customer** is for building **universal** apps and websites that interact with a subset of hAPI available to customers of a particular store. This export is also available as a pre-built library on our CDN.\n3. **Core**: is for building custom API clients that interact with Hypermedia API endpoints. This is the most advanced part of the SDK that every other built-in API client depends on. You can run it server and client-side.\n\nBackend and Customer export API client classes for working with the respective endpoints. If you're using TypeScript, you'll also see the type exports for API-specific hypermedia relations and graphs named `Rels` and `Graph`. Let's connect to hAPI using `FoxySDK.Backend.API` class:\n\n```js\nconst api = new FoxySDK.Backend.API({\n  refreshToken: 'your refresh token',\n  clientSecret: 'your client secret',\n  clientId: 'your client id',\n});\n```\n\nThis will create a hAPI version 1 client connecting to `https://api.foxy.io/` with the given credentials, using in-memory storage for access token and URL resolution, logging errors, warnings and informational messages to console. You can customize each one of these defaults in constructor params and you'll see similar options for Customer API as well.\n\nRegardless of the API type you're working with, you'll see the same methods on each node: `.follow()`, `.get()`, `.put()`, `.post()`, `.patch()` and `.delete()`. Here's how you can use them in 3 steps:\n\n### 1. Find a node\n\nTo access a hAPI endpoint, you don't type in a URL – instead you traverse the API graph via links until you reach your target. For example, to see your transactions, you need to load the bookmark URL (`https://api.foxy.io/`), load your store at `bookmark._links['fx:store'].href` and only then get to the transactions at `store._links['fx:transactions'].href`. With our SDK this lengthy process becomes a one-liner:\n\n```js\nconst transactionsNode = api.follow('fx:store').follow('fx:transactions');\n```\n\nString bits that start with `fx:` are called Compact URIs (or curies for short), and if you're using an editor that supports code autocompletion based on TypeScript definitions, we'll provide suggestions for available curies where possible.\n\nNow that we have our node, let's get some data from it:\n\n### 2. Get some data\n\nEach node has a class method corresponding to a supported HTTP method. For example, to make a `GET` request, we can call `.get()`:\n\n```js\nconst transactionsResponse = await transactionsNode.get();\n```\n\nThe method we've just called returns a Promise (hence the use of the `await` keyword) that resolves with an enhanced version of a native [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object, giving you an ability to access response status, headers and more. But for now we just want our JSON:\n\n```js\nconst transactions = await transactionsResponse.json();\n```\n\nDone! Now you have the API response with the same schema as in the [docs](https://api.foxy.io/) at your disposal. And yes, we have type definitions for it too, meaning that you'll get type checking with TypeScript and rich autosuggestions with inline docs in every editor that supports them. But what if we could go even further?\n\n### 3. Making complex queries\n\nQuite often you'll need to fetch a specific set of items, maybe apply some filters, skip a few entries, speed things up by requesting a partial resource – and you can do that with hAPI using query parameters from our [cheatsheet](https://api.foxy.io/docs/cheat-sheet). Our SDK provides convenient shortcuts for these parameters in the `.get()` method (all optional):\n\n```js\nconst transactionsResponse = await transactionsNode.get({\n  zoom: { customer: ['default_billing_address'] },\n  filters: ['total_order:greaterthan=50', 'attributes:name[color]=red'],\n  fields: ['id', 'total_order', 'currency_code'],\n  offset: 25,\n  limit: 10,\n});\n```\n\nThe response type will also match your query as close as possible, giving you the ability to eliminate possible errors before hitting the API. For example, for the above request each transaction will have only those 3 fields and only those 2 nested embeds (+ attributes where supported as they're included by default).\n\n### Bonus: followable responses\n\nEach link in the `_links` object received from our SDK includes the same methods as a regular node, so you can do something like this:\n\n```js\nconst nextTransactionsPage = await transactions._links.next.get();\n```\n\nIt also works with embedded resources and following, and you'll get autocompletion and type checking all the way through:\n\n```js\nconst recentSubscriptions = await transactions._embedded['fx:customer']._links['fx:subscriptions'].follow('last').get();\n```\n\n## Development\n\nTo get started, clone this repo locally and install the dependencies:\n\n```bash\ngit clone https://github.com/foxy/foxy-sdk.git \u0026\u0026 cd foxy-sdk \u0026\u0026 npm i\n```\n\nYou can also build this package and test it locally in another project by running the following in the project folder:\n\n```bash\nnpm pack\n```\n\nUse the following commands to run tests:\n\n```bash\nnpm test # run all tests\nnpm run test:watch # watch files for changes and re-run relevant tests\n```\n\nAll the latest features are published from the [beta](https://github.com/Foxy/foxy-sdk/tree/beta) branch to the `beta` distribution channel. If you submit a PR, please target `beta` as well. Releases are published from [main](https://github.com/Foxy/foxy-sdk/tree/main).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoxy%2Ffoxy-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoxy%2Ffoxy-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoxy%2Ffoxy-sdk/lists"}