\n\nThis package creates a Nuki GraphQL API, allowing for interaction with data at Nuki.\n**It is unofficial Nuki GraphQL API generated based on Nuki's Swagger OpenAPI specification,\nmainly configured to be used as Hasura Remote Schema.**\n\nHere's an example of how to use the Nuki GraphQL API to get a list of smart locks of the configured Nuki user:\n\n```graphql\nquery MyLocks {\n nuki {\n smartlocks {\n name\n smartlockId\n state {\n batteryCharge\n state\n }\n firmwareVersion\n hardwareVersion\n }\n }\n}\n```\n\nIt's recommended to add the Nuki GraphQL API as a [Remote Schema](https://hasura.io/docs/latest/remote-schemas/index/) in Hasura and connect data from your database with data in Nuki. By doing so, it's possible to request data from your database and Nuki in a single GraphQL query.\n\nHere's an example of how to use the Nuki GraphQL API to get a list of smart locks for a specific Nuki user. Note that the user data is fetched from your database and the Nuki user data is fetched trough the Nuki API:\n\n```graphql\nquery UsersLocks {\n users {\n id\n displayName\n nukies {\n # Remote schema relation in users table\n name\n smartlockId\n state {\n batteryCharge\n state\n }\n firmwareVersion\n hardwareVersion\n }\n }\n}\n```\n\n## Supported APIs\n\nAPIs can be added upon request. PRs are welcome of course!\n\nhttps://api.nuki.io\n\n| Api | Supported | Comment |\n| ------------------- | :-------: | ----------------------------------------- |\n| Account | 🟠| |\n| AccountSubscription | 🔴 | |\n| AccountUser | 🔴 | |\n| Address | 🔴 | |\n| AddressReservation | 🔴 | |\n| AddressToken | 🔴 | |\n| AdvancedApi | 🟠| |\n| ApiKey | 🔴 | |\n| Company | 🔴 | |\n| Notification | 🔴 | |\n| Opener | 🔴 | |\n| Service | 🔴 | |\n| Smartlock | 🟠| |\n| SmartlockAuth | 🔴 | |\n| SmartlockLog | 🟢 | Available nested inside `smartlock` query |\n| Subscription | 🔴 | |\n\n🟢 - Supported\n🟠- Partial\n🔴 - Not supported\n\n## Getting Started\n\nInstall the package:\n\n```\npnpm add @dodi-smart/nuki-graphql-api\n```\n\n### Setup serverless function\n\nCreate a new [Serverless Function](https://docs.nhost.io/serverless-functions): `functions/graphql/nuki.ts`:\n\n```ts\nimport { createNukiGraphQLServer } from '@dodi-smart/nuki-graphql-api'\n\nconst server = createNukiGraphQLServer({\n graphiql: true,\n graphqlEndpoint: '/graphql/nuki',\n healthCheckEndpoint: '/graphql/nuki/health',\n provideAuth(context) {\n return {\n // Should provide authentication\n }\n },\n onUpdateSession(context, auth) {\n // Handle session update\n }\n})\n\nexport default server\n```\n\n### Configure Nuki Web\n\nGo to [Nuki Web](https://web.nuki.io/#/pages/web-api) and obtain OAuth2 API key and secret.\nClick on `Generate API token`, give the token name and check the scopes you want to use. Click save and copy the token value.\n\n- Add `NUKI_CLIENT_ID` as an environment variable.\n- Add `NUKI_CLIENT_SECERT` as an environment variable.\n- Add `NUKI_API_KEY` as an environment variable.\n\nIf you're using Nhost, add `NUKI_CLIENT_ID`, `NUKI_CLIENT_SECERT` and `NUKI_API_KEY` to `.env.development` like this:\n\n```ini\nNUKI_CLIENT_ID=6EYY••••\nNUKI_CLIENT_SECERT=BPum••••\nNUKI_API_KEY=59f6d••••\n```\n\nAnd add the production key values to environment variables in the Nhost dashboard.\n\n### Start Nhost\n\n```sh\nnhost up\n```\n\nLearn more about the [Nhost CLI](https://docs.nhost.io/cli).\n\n### Test\n\nTest the Nuki GraphQL API in the browser:\n\nhttps://local.functions.nhost.run/v1/graphql/nuki\n\n### Remote Schema\n\nAdd the Nuki GraphQL API as a Remote Schema in Hasura.\n\n**URL**\n\n```\n{{NHOST_FUNCTIONS_URL}}/graphql/nuki\n```\n\n**Headers**\n\n```\nx-nhost-webhook-secret: NHOST_WEBHOOK_SECRET (From env var)\n```\n\n> The `NHOST_WEBHOOK_SECRET` is used to verify that the request is coming from Nhost. The environment variable is a [system environment variable](/platform/environment-variables#system-environment-variables) and is always available.\n\n## Authentication\n\nYou have several options to authentication your users agains Nuki using this library. All of them depends on the usecase:\n\n**Single user usecase (easy to setup)**\n\nWhen the system should work with the locks of a single user (administrator). Permissions and access to the locks are granted to others users via the administrator\nor using Hasura user roles.\n\n**Multi user usecase (advanced)**\n\nWhen system work with locks of multiple users. Each user can authenticate against Nuki using their own credentials via OAuth 2.0.\nThis usecase can be used for multi tenant apps for example.\n\n### How to choose\n\n| Use case | Using API_KEY (easy) | OAuth 2.0 (advanced) | OAuth 2.0 + ApiKeyToken (advanced) |\n| ----------- | :------------------: | :------------------: | :--------------------------------: |\n| Single user | 🟢 | 🟠| 🟠|\n| Multi user | 🔴 | 🟠| 🟢 |\n\n🟢 - Preferable way\n🟠- Supported\n🔴 - Not supported\n\n### Using API_KEY\n\nGo to [Nuki Web](https://web.nuki.io/#/pages/web-api) and click on API on side navigation\n\nClick on `Generate API token`, give the token name and check the scopes you want to use. Click save and copy the token value.\n`ApiKeyToken` is long-living token and does not require refresh.\n\n- Add `NUKI_API_KEY` as an environment variable.\n\nIf you're using Nhost, add `NUKI_API_KEY` to `.env.development` like this:\n\n```ini\nNUKI_API_KEY=59f6d••••\n```\n\nAnd add the production key values to environment variables in the Nhost dashboard.\n\n#### (Optional) Modify Remote Schema\n\nIf you need to pass the API key from Hasura instead of having it as environment variable, then:\n\nAdd to the Hasura Remote Schema the API Key\n\n```\nx-nuki-api-key: NUKI_API_KEY (From env var)\n```\n\nThe environment variable is a [system environment variable](/platform/environment-variables#system-environment-variables) and is always available.\n\n#### Configure the Nuki GraphQL API\n\n```ts\nimport { createNukiGraphQLServer } from '@dodi-smart/nuki-graphql-api'\n\nconst server = createNukiGraphQLServer({\n graphqlEndpoint: '/graphql/nuki',\n healthCheckEndpoint: '/graphql/nuki/health',\n provideAuth(context) {\n const { request } = context\n return {\n // Is enough to pass just the accessToken\n accessToken: request.headers.get('x-nuki-api-key')\n }\n },\n onUpdateSession(context, auth) {\n // Can be empty as NUKI_API_KEY are long-living tokens\n }\n})\n\nexport default server\n```\n\n### OAuth 2.0\n\nGo to [Nuki Web](https://web.nuki.io/#/pages/web-api) and click on API on side navigation\n\nPoint OAuth2 Redirect URL to a Nhost serverless function:\n\n```\nhttps://local.functions.nhost.run/v1/callback/nuki\n```\n\n#### Use callback helper function to get session\n\nCreate a new [Serverless Function](https://docs.nhost.io/serverless-functions): `functions/callback/nuki.ts`:\n\n```ts\nimport { createNukiOAuthCallback } from '@dodi-smart/nuki-graphql-api'\n\nconst handler = (req, res) => {\n const {userId, accessToken, refreshToken} = createNukiOAuthCallback(req, res)\n await gqlSDK.updateUserNukiAuth({\n id: userId,\n accessToken,\n refreshToken\n })\n}\n\nexport default handler\n```\n\n#### Configure the Nuki GraphQL API\n\n```ts\nimport { createNukiGraphQLServer } from '@dodi-smart/nuki-graphql-api'\n\nconst server = createNukiGraphQLServer({\n graphqlEndpoint: '/graphql/nuki',\n healthCheckEndpoint: '/graphql/nuki/health',\n provideAuth(context) {\n const { userClaims } = context\n\n const { user } = await gqlSDK.getUser({\n id: userId\n })\n\n return {\n // Example if nuki creds are saved in user's metadata, can differ\n accessToken: user.metadata.nukiAccessToken,\n refreshToken: user.metadata.nukiRefreshToken,\n }\n },\n onUpdateSession(context, auth) {\n const { userClaims } = context\n const { accessToken, refreshToken } = auth\n\n await gqlSDK.updateUserNukiAuth({\n id: userId,\n accessToken,\n refreshToken\n })\n }\n})\n\nexport default server\n```\n\n### OAuth 2.0 + ApiKeyToken creation\n\nThis is very similar to previous option with the different that after first login,\nan `ApiKeyToken` is automatically created and can be used instead of refreshing user session.\n`ApiKeyToken` is long-living token and does not require refresh or anything.\n\nGo to [Nuki Web](https://web.nuki.io/#/pages/web-api) and click on API on side navigation\n\nPoint OAuth2 Redirect URL to a Nhost serverless function:\n\n```\nhttps://local.functions.nhost.run/v1/callback/nuki\n```\n\n#### (Optional) Enable key creation via env\n\nApi key creation can be enabled via environment variable or via code. If you like to use env variable follow the steps below,\nskip the section and check how to enable it via the function code.\n\n- Add `NUKI_API_KEY_CREATE` as an environment variable.\n\nIf you're using Nhost, add `NUKI_API_KEY_CREATE` to `.env.development` like this:\n\n```ini\nNUKI_API_KEY_CREATE=true\n```\n\n#### Create API token using the callback\n\nCreate a new [Serverless Function](https://docs.nhost.io/serverless-functions): `functions/callback/nuki.ts`:\n\n```ts\nimport { createNukiOAuthCallback } from '@dodi-smart/nuki-graphql-api'\n\nconst handler = (req, res) => {\n const {userId, apiKeyToken} = createNukiOAuthCallback(req, res, true)\n await gqlSDK.updateUserNukiAuth({\n id: userId,\n apiKey: apiKeyToken\n })\n}\n\nexport default handler\n```\n\n#### Configure the Nuki GraphQL API\n\n```ts\nimport { createNukiGraphQLServer } from '@dodi-smart/nuki-graphql-api'\n\nconst server = createNukiGraphQLServer({\n graphqlEndpoint: '/graphql/nuki',\n healthCheckEndpoint: '/graphql/nuki/health',\n provideAuth(context) {\n const { userClaims } = context\n\n const { user } = await gqlSDK.getUser({\n id: userId\n })\n\n return {\n // Example if nukiApiKey is saved in user's metadata, can differ\n accessToken: user.metadata.nukiApiKey,\n }\n },\n onUpdateSession(context, auth) {\n // Can be empty as API Keys are long-living tokens\n }\n})\n\nexport default server\n```\n\n## Permissions\n\nHere's a minimal example without any custom permissions. Only requests using the `x-hasura-admin-secret` header will work:\n\n```ts\nimport { createNukiGraphQLServer } from '@dodi-smart/nuki-graphql-api'\n\nconst server = createNukiGraphQLServer({\n graphqlEndpoint: '/graphql/nuki',\n healthCheckEndpoint: '/graphql/nuki/health',\n provideAuth(context) {\n /* ... */\n },\n onUpdateSession(context, auth) {\n /* ... */\n }\n})\n\nexport default server\n```\n\nFor more granular permissions, you can pass an `isAllowed` function to the `createNukiGraphQLServer`. The `isAllowed` function takes a [`context`](#context) as parameter and runs every time the GraphQL server makes a request to Nuki to get or modify data for a specific Nuki user.\n\nHere is an example of an `isAllowed` function:\n\n```ts\nimport { createNukiGraphQLServer } from '@dodi-smart/nuki-graphql-api';\n\nconst isAllowed = (context: Context) => {\n const { isAdmin, userClaims } = context\n\n // allow all requests if they have a valid `x-hasura-admin-secret`\n if (isAdmin) {\n return true\n }\n\n // get user id\n const userId = userClaims['x-hasura-user-id']\n\n // check if the user is signed in\n if (!userId) {\n return false\n }\n\n // get more user information from the database\n const { user } = await gqlSDK.getUser({\n id: userId\n })\n\n if (!user) {\n return false\n }\n\n // other checks\n}\n\nconst server = createNukiGraphQLServer({\n graphqlEndpoint: '/graphql/nuki',\n healthCheckEndpoint: '/graphql/nuki/health',\n isAllowed,\n provideAuth(context) {\n /* ... */\n },\n onUpdateSession(context, auth) {\n /* ... */\n }\n});\n\nexport default server;\n```\n\n### Context\n\nThe `context` object contains:\n\n- `userClaims` - verified JWT claims from the user's access token.\n- `isAdmin` - `true` if the request was made using a valid `x-hasura-admin-secret` header.\n- `request` - [Fetch API Request object](https://developer.mozilla.org/en-US/docs/Web/API/Request) that represents the incoming HTTP request in platform-independent way. It can be useful for accessing headers to authenticate a user\n- `query` - the DocumentNode that was parsed from the GraphQL query string\n- `operationName` - the operation name selected from the incoming query\n- `variables` - the variables that were defined in the query\n- `extensions` - the extensions that were received from the client\n\nRead more about the [default context from GraphQL Yoga](https://www.the-guild.dev/graphql/yoga-server/docs/features/context#default-context).\n","readmeFilename":"README.md"}
![\"nuki\"](\"https://assets.ifttt.com/images/channels/1521185749/icons/on_color_large.png\"){kind=icon}
\n![\"npm\"](\"https://img.shields.io/npm/v/@dodi-smart/nuki-graphql-api\")
![\"npm\"](\"https://img.shields.io/npm/dm/@dodi-smart/nuki-graphql-api\")
![\"NPM\"](\"https://img.shields.io/npm/l/@dodi-smart/nuki-graphql-api\")