{"_id":"@alexgilleran/partner-api","name":"@alexgilleran/partner-api","dist-tags":{"latest":"2.2.0"},"versions":{"2.2.0":{"name":"@alexgilleran/partner-api","private":false,"version":"2.2.0","main":"dist/index.js","typings":"dist/types","license":"MIT","description":"Provides convenient access to Duda's public APIs from applications written in server-side Javascript.","repository":{"type":"git","url":"git+https://github.com/DudaDev/partner-api.git"},"homepage":"https://github.com/DudaDev/partner-api#readme","author":{"name":"DudaDev"},"scripts":{"tsc":"./node_modules/typescript/bin/tsc","test":"npm run linter && nyc npm run tests","linter":"eslint --ext .ts src/","tests":"env TS_NODE_COMPILER_OPTIONS='{\"module\": \"commonjs\" }' node ./node_modules/mocha/bin/mocha -r ./node_modules/ts-node/register/index.js 'tests/**/*.ts'","test:file":"env TS_NODE_COMPILER_OPTIONS='{\"module\": \"commonjs\" }' node ./node_modules/mocha/bin/mocha -r ./node_modules/ts-node/register/index.js \"tests/**/$FILENAME.ts\"","test-publish":"npm publish --dry-run","prod-publish":"npm run tsc && npm publish","prepublishOnly":"npm run test","preversion":"npm run test"},"dependencies":{"ejmorgan-retry":"^1.0.6","uuid":"^8.3.2"},"devDependencies":{"@types/chai":"^4.3.1","@types/mocha":"^9.1.1","@types/node":"^16.11.10","@types/uuid":"^8.3.4","@typescript-eslint/eslint-plugin":"^5.4.0","@typescript-eslint/parser":"^5.4.0","chai":"^4.3.6","chai-as-promised":"^7.1.1","eslint":"^8.3.0","eslint-config-airbnb-base":"^15.0.0","eslint-plugin-import":"^2.25.3","mocha":"^10.0.0","nock":"^13.2.4","nyc":"^15.1.0","ts-node":"^10.8.0","typescript":"^4.5.2"},"gitHead":"2867a46af2d6735aa5ec2abc8fad80cec561d603","bugs":{"url":"https://github.com/DudaDev/partner-api/issues"},"_id":"@alexgilleran/partner-api@2.2.0","_nodeVersion":"18.16.0","_npmVersion":"9.5.1","dist":{"integrity":"sha512-v4fyS+/c6pTrrBiPN7AS+42S1jgeZYd+02kxlCfxDcDOPkvIpyAVNP6X5Wf63CDoaWL8s4mlVoCJPI9Ei+75dQ==","shasum":"cf135feee5a3115b905bcab978d8c3736e01cdcf","tarball":"https://registry.npmjs.org/@alexgilleran/partner-api/-/partner-api-2.2.0.tgz","fileCount":261,"unpackedSize":352398,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDrgbISFGSb3elCibtJYxrp18Ry0rngcefynEuuWS8ssAIgHI8FL1phnzpgK+9RRF8MJlVs8lltzXVxS4v1j+Xpldc="}]},"_npmUser":{"name":"alexgilleran","email":"alex@alexgilleran.com"},"directories":{},"maintainers":[{"name":"alexgilleran","email":"alex@alexgilleran.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/partner-api_2.2.0_1690501089571_0.7754664176018673"},"_hasShrinkwrap":false}},"time":{"created":"2023-07-27T23:38:09.430Z","2.2.0":"2023-07-27T23:38:09.779Z","modified":"2023-07-27T23:38:10.092Z"},"maintainers":[{"name":"alexgilleran","email":"alex@alexgilleran.com"}],"description":"Provides convenient access to Duda's public APIs from applications written in server-side Javascript.","homepage":"https://github.com/DudaDev/partner-api#readme","repository":{"type":"git","url":"git+https://github.com/DudaDev/partner-api.git"},"author":{"name":"DudaDev"},"bugs":{"url":"https://github.com/DudaDev/partner-api/issues"},"license":"MIT","readme":"# @dudadev/partner-api\n\nThe `@dudadev/partner-api` library provides convenient access to Duda's public APIs from applications written in\nserver-side Javascript.\n\n1. [Requirements](#requirements)\n2. [Installation](#installation)\n3. [Usage](#usage)\n4. [Configuration](#configuration)\n    1. [Initialize with config object](#initialize-with-config-object)\n    2. [API Environments](#api-environments)\n    3. [Network Retries](#network-retries)\n5. [Request Overrides](#request-overrides)\n6. [Responses](#responses)\n    1. [Success](#success)\n    2. [Errors](#errors)\n7. [Debugging](#debugging)\n8. [App Store](#app-store-api)\n    1. [Authenticating requests](#authenticating-requests)\n    2. [Handling different `api_endpoint` values](#handling-different-api_endpoint-values)\n    3. [Utility functions](#utility-functions)\n9. [More Information](#more-information)\n\n## Requirements\n\nNode v14 or higher.\n\n## Installation\n\nInstall the package with:\n\n```bash\nnpm install @dudadev/partner-api --save\n# or\nyarn add @dudadev/partner-api\n```\n\n## Usage\n\nThe package needs to be configured with your API credentials:\n\n```typescript\nconst { Duda } = require('@dudadev/partner-api');\n\nconst duda = new Duda({\n  user: process.env.DUDA_API_USER,\n  pass: process.env.DUDA_API_PASS,\n  env: Duda.Envs.direct,\n});\n\nduda.sites.get({ site_name: \"a-site-name\" })\n  .then(site => console.log(site))\n  .catch(error => console.error(error));\n```\n\nOr using ES modules and `async/await`:\n\n```typescript\n// async / await\n(async function () {\n  try {\n    const site = await duda.sites.get({ site_name: \"a-site-name\" });\n    console.log(site);\n  } catch (error) {\n    console.log(error.status, error.error);\n    // handle error\n  }\n})();\n```\n\n## Configuration\n\n### Initialize with config object\n\nThe package can be initialized with several options:\n\n```typescript\nconst duda = new Duda({\n  user: 'api-user',\n  pass: 'api-pass',\n  env: Duda.Envs.sandbox, // also, .direct, .eu\n});\n```\n\n### API Environments\n\n- `Duda.Envs.eu`: api.eu.duda.co\n- `Duda.Envs.direct`: api.duda.co\n- `Duda.Envs.sandbox`: api-sandbox.duda.co\n\n### Request Timeout\n\nThe request timeout limit. The maximum number of milliseconds before a request is considered to be timed out. This will trigger a timeout event handler and reject the promise with an `ECONNRESET` error code. This option defaults to 10000ms.\n\n```typescript\nconst duda = new Duda({\n  ...,\n  timeout: 1000\n});\n```\n\n### Network Retries\n\nAutomatic network retries can be enabled with the maxNetworkRetries config option. This will retry requests n times with exponential backoff if they fail due to an intermittent network problem. It's recommended you also set the `timeout` config option when enabling retries. Keep in mind that the timeout config is related to the timeout of the request, it does not affect the timing of the exponential backoff.\n\n```typescript\nconst duda = new Duda({\n  ...,\n  maxNetworkRetries: 2,\n  timeout: 1000\n});\n```\n\n## Request Overrides\n\nYou can override\nthe [http.RequestOptions](https://definitelytyped.org/docs/node--node/interfaces/https.requestoptions.html)\nof any method on a per-request basis by passing a second object with custom options:\n\n```typescript\nconst { Duda } = require('@dudadev/partner-api');\n\nconst duda = new Duda({\n  user: process.env.DUDA_API_USER,\n  pass: process.env.DUDA_API_PASS,\n  env: Duda.Envs.direct,\n});\n\nduda.sites.get({ site_name: 'a-site-name' }, {\n  host: 'api-special.duda.co',\n  auth: 'another-username:another-password',\n  headers: {\n    'X-CUSTOM-HEADER': 'a-value',\n  },\n})\n  .then((site) => console.log(site))\n  .catch((error) => console.error(error))\n```\n\n## Responses\n\n### Success\n\nThe library will attempt to parse all successful responses as JSON, and will return the raw value if it can't.\n\n### Errors\n\nThe library will either throw (for promises) or return (for callbacks) the following payload after receiving a status\ncode >= 400:\n\n```typescript\ninterface ErrorResponse<DudaError> {\n  status: number;\n  error: DudaError;\n}\n```\n\n## Debugging\n\nYou can debug requests made by the library by setting the `DUDA_API_LOG_LEVEL` environment variable to one of the\nfollowing levels:\n\n1. error: only shows fatal errors\n2. warning: shows all errors and warnings\n3. info: high-level debugging information\n4. debug: verbose debugging information\n\nThe library will display logs that are >= `DUDA_API_LOG_LEVEL`. So, for example, setting the log level to warning (2)\nwould log all warnings (2) and errors (1).\n\nThe logger will attempt to redact any sensitive information before it logs using the following regular expressions:\n\n- `/(user(name)?|pass(word)?|auth(orization)?)\":\"[^\"]+/gi`\n- `/(Bearer|Basic) [^\"]+/gi`\n\n### Example using `debug`\n\n```bash\n$ DUDA_API_LOG_LEVEL=debug node index.js\n[debug] 8ce2a72d-d6b6-4fe8-bf39-45ebe99f7233 no http agent defined: received=undefined\n[info] 8ce2a72d-d6b6-4fe8-bf39-45ebe99f7233 new request: method=get endpoint=api-sandbox.duda.co/api/sites/multiscreen/374f37ea1eff44e7966b2c685ded251a/pages\n[debug] 8ce2a72d-d6b6-4fe8-bf39-45ebe99f7233 full request details: req={\"headers\":{},\"method\":\"get\",\"path\":\"/api/sites/multiscreen/374f37ea1eff44e7966b2c685ded251a/pages\",\"auth\": [redacted],\"host\":\"api-sandbox.duda.co\"}\n[debug] 8ce2a72d-d6b6-4fe8-bf39-45ebe99f7233 data received: raw={\"results\":[{\"uuid\":\"683340afe033436caab26cf8a548b1dd\",\"title\":\"Home\",\"path\":\"home\",\"seo\":{\"no_index\":false}}]}\n[debug] 8ce2a72d-d6b6-4fe8-bf39-45ebe99f7233 request ended: status=200 time=0.51s\n```\n\n## App Store API\n\nIf you're an app developer, you can access the App Store API under `duda.appstore` after calling `new Duda(opts)`.\n\n### Authenticating requests\n\nAPI Endpoints protected by an `X-DUDA-ACCESS-TOKEN` expect method calls to include a `token` property set to the\n`authorization_code` **without** `Bearer` included.\n\n```typescript\nduda.appstore.sites.get({\n  site_name: 'a-site-name',\n  token: 'authorization-code',\n})\n```\n\n### Handling different `api_endpoint` values\n\nYou can use the [request override](#request-overrides) feature to set the host of a method call to the correct\n`api_endpoint` for a particular site.\n\n```typescript\nfunction getSite(site: string) {\n  const {\n    site_name,\n    auth,\n    api_endpoint\n  } = getInstallFromDB(site);\n\n  return duda.appstore.sites.get({\n    site_name: site_name,\n    token: auth.authorization_code,\n  }, {\n    host: api_endpoint,\n  })\n}\n\ngetSite('a-site-name')\n  .then((site) => console.log(site))\n  .catch((err) => console.log(err.status, err.error))\n```\n\n### Utility functions\n\nIncluded under `Duda.appstore` is `utils` which contains useful methods for validating webhooks & signatures.\n\n```typescript\nfunction validateWebook(req: YourRequestObject): boolean {\n  // conform request object\n  return duda.appstore.utils.validateWebook(process.env.SECRET_KEY, req.headers, req.body);\n}\n\nfunction validateSSO(req: YourRequestObject): boolean {\n  // conform request object\n  return duda.appstore.utils.validateSSOLink(process.env.SECRET_KEY, req.query);\n}\n```\n\n## More Information\n\n- [REST API Reference](https://developer.duda.co/reference#getting-started-with-the-duda-api)\n","readmeFilename":"README.md"}