{"id":11516,"library":"paapi5-typescript-sdk","title":"Amazon Product Advertising API 5.0 TypeScript SDK","description":"The `paapi5-typescript-sdk` is an unofficial TypeScript SDK designed for interacting with Amazon's Product Advertising API 5.0. As of its latest release, v0.2.0, it provides a comprehensive set of classes and types for constructing and sending requests such as `SearchItemsRequest`, `GetItemsRequest`, and `GetBrowseNodesRequest`. The library internally handles the AWS V4 signing process via the `SignHelper` class, abstracting away much of the authentication complexity. Being unofficial, its development and alignment with Amazon's API updates are dependent on the maintainer. It ships with full TypeScript types, making it ideal for type-safe Node.js environments. This SDK simplifies interaction with PAAPI 5.0, which migrated from XML to JSON responses and deprecated PAAPI 4.0 in 2020. While Amazon provides official SDKs for other languages like Python, this TypeScript version fills a gap for Node.js developers seeking a type-safe interface.","status":"active","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/Pigotz/paapi5-typescript-sdk","tags":["javascript","amazon","aws","paapi5","typescript","node"],"install":[{"cmd":"npm install paapi5-typescript-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add paapi5-typescript-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add paapi5-typescript-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library is TypeScript-first and designed for ESM. While CommonJS might technically work with transpilation, direct `import` is the idiomatic and intended usage.","wrong":"const SDK = require('paapi5-typescript-sdk');","symbol":"SDK","correct":"import * as SDK from 'paapi5-typescript-sdk';"},{"note":"All major components, including utility classes and enums, are exported directly from the root package. Avoid deep imports as internal paths are not guaranteed stable.","wrong":"import SignHelper from 'paapi5-typescript-sdk/auth/signHelper';","symbol":"SignHelper, Region, HttpMethod","correct":"import { SignHelper, Region, HttpMethod } from 'paapi5-typescript-sdk';"},{"note":"Request classes and related enums (PartnerType, Host) are top-level exports, simplifying access without needing to navigate internal directory structures.","wrong":"import { GetItemsRequest } from 'paapi5-typescript-sdk/requests';","symbol":"GetItemsRequest, PartnerType, Host","correct":"import { GetItemsRequest, PartnerType, Host } from 'paapi5-typescript-sdk';"}],"quickstart":{"code":"import { GetItemsRequest, PartnerType, Host, Region } from 'paapi5-typescript-sdk';\n\nasync function fetchAmazonProductDetails(asin: string) {\n  const partnerTag = process.env.PA_API_PARTNER_TAG ?? 'YOUR_PARTNER_TAG';\n  const accessKey = process.env.PA_API_ACCESS_KEY ?? 'YOUR_ACCESS_KEY';\n  const secretKey = process.env.PA_API_SECRET_KEY ?? 'YOUR_SECRET_KEY';\n\n  // Ensure you use the correct Host and Region for your desired marketplace\n  // e.g., Host.UnitedStates and Region.UNITED_STATES for amazon.com\n  const request = new GetItemsRequest(\n    {\n      ItemIds: [asin],\n      Resources: [\n        'Images.Primary.Large',\n        'ItemInfo.Title',\n        'Offers.Listings.Price'\n      ],\n    },\n    partnerTag,\n    PartnerType.ASSOCIATES,\n    accessKey,\n    secretKey,\n    Host.Italy, // Example: Using Italy. Change as needed.\n    Region.ITALY  // Example: Using Italy. Change as needed.\n  );\n\n  try {\n    const data = await request.send();\n    console.log(`Successfully fetched details for ASIN ${asin}:`);\n    console.log(JSON.stringify(data, null, 2));\n    return data;\n  } catch (error) {\n    console.error(`Error fetching details for ASIN ${asin}:`, error);\n    throw error;\n  }\n}\n\n// Example usage (replace with a real ASIN from amazon.it if using Italy locale)\n// Make sure to set PA_API_PARTNER_TAG, PA_API_ACCESS_KEY, PA_API_SECRET_KEY\n// in your environment variables or replace the placeholders.\nfetchAmazonProductDetails('B07WGNF455')\n  .then(() => console.log('Product fetch complete.'))\n  .catch(() => console.error('Failed to fetch product.'));","lang":"typescript","description":"This quickstart demonstrates how to instantiate and send a `GetItemsRequest` to Amazon's Product Advertising API 5.0, fetching product details by ASIN."},"warnings":[{"fix":"Be prepared to manually update the SDK or fork it if Amazon introduces breaking changes to PAAPI 5.0 that are not promptly addressed by this library's maintainer.","message":"This is an *unofficial* SDK. It is not directly maintained or supported by Amazon. While functional, it may not receive updates synchronously with Amazon's official API changes or provide the same level of support as official SDKs.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Always review the release notes or GitHub commit history when upgrading to new versions, even minor ones. Thorough testing after upgrades is recommended.","message":"The SDK is in early development (v0.2.0). Breaking changes to its API surface, class structures, or method signatures are possible even between minor or patch versions, without adhering to strict semver for stability.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"If authentication errors persist, verify the custom `SignHelper` implementation against the official AWS V4 signing documentation. Consider using AWS's own signing libraries if you encounter persistent issues.","message":"The library implements the AWS V4 signing process from scratch using the `SignHelper` class. While this offers self-containment, it might subtly differ from official AWS SDK implementations or become outdated if AWS updates its signing algorithm, potentially leading to authentication failures.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Always ensure the `Host` and `Region` enums passed to request constructors (or `CommonRequest`) accurately reflect the Amazon locale (e.g., `Host.UnitedStates` for `amazon.com`) and your AWS credentials' region.","message":"Incorrect configuration of `Host` and `Region` parameters can lead to 'SignatureDoesNotMatch' or 'InvalidParameterValue' errors. These must precisely match the Amazon marketplace you are targeting and the region associated with your AWS credentials.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Implement proper error handling with exponential backoff and retry mechanisms for API requests. Review Amazon's PAAPI 5.0 documentation on request limits and best practices for making API calls.","message":"The Amazon Product Advertising API 5.0 has strict request throttling and resource limits. Exceeding these limits will result in API errors (e.g., HTTP 503 Service Unavailable or specific error codes from PAAPI 5.0).","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Double-check your `accessKey`, `secretKey`, `partnerTag`, `Host`, and `Region` values. Ensure they are correct for the Amazon marketplace you are targeting and that your keys are active and valid for PAAPI 5.0. Use the official PAAPI 5.0 Scratchpad to validate your credentials and parameters outside of the SDK.","cause":"Invalid AWS Access Key, Secret Key, Partner Tag, or mismatch between the specified Host/Region and your credentials. The custom signing process requires exact matches.","error":"SignatureDoesNotMatch"},{"fix":"Verify that `SignHelper` is instantiated with the correct credentials and that its output, specifically the `Authorization` header, is properly incorporated into the outgoing request. Ensure all required headers like `x-amz-date`, `host`, `x-amz-target`, and `content-type` are present and correctly formatted.","cause":"The authentication headers required for AWS V4 signing were not correctly generated or included in the HTTP request. This often indicates an issue with `SignHelper` initialization or its integration.","error":"MissingAuthenticationToken"},{"fix":"Consult the official Amazon Product Advertising API 5.0 documentation for the exact request type (e.g., `GetItems`, `SearchItems`) and its required parameters. Ensure all fields are correctly named, have valid values, and that required fields are not missing. Pay attention to case sensitivity and expected data types.","cause":"One or more request parameters (e.g., ItemIds, Resources, keywords for SearchItems) do not conform to the Amazon Product Advertising API 5.0 specification for the specific operation.","error":"Bad Request (or similar with specific 'InvalidParameterValue' details in response payload)"}],"ecosystem":"npm"}