This CDK package shows an example of utilizing Buy with Prime's events and API. This package is based on the Mock API and Mock events, not the Buy with Prime production API, or production events. If you do not have a Buy with Prime Accelerator to generate Mock APIs and Mock Events, please request one from your Buy with Prime SA. If you don't have point of contact, please reach out to [email protected].

This sample demonstrates an example of event hydration for:

• order event : ORDER_PLACED, ORDER_UPDATED, REFUND_SUCCESS.
• buyability and inventory event

The order event stack extracts an orderId from a mock order event. Using that ID, the stack calls the Buy with Prime Mock API to query information about a single order. You can see the Buy with Prime query example in singleOrder.graphql and it's sample query response. This sample code stores the response in a format of text file. You can see the actual example from sample object.

• Inventory event: Work in Progress. The event hydrator checks if the event has identifierType as an itemId. If so, it extracts identifierValue, which is a unique itemId. Using that ID, the Lambda function sends the item query to the Buy with Prime Mock API. You can see the item query in itemByID.graphql and it's sample query response.

1. Deploy Buy with Prime accelerator in your AWS account.
2. Prepare your S3 bucket to store Buy with Prime data.

• AWS Secrets Manager
• Amazon EventBridge
• Amazon SQS and Dead Letter Queue
• AWS Lambda
• Amazon S3

The lambda function hydrates Buy with Prime events, parsing orderId, sends order query as written in singleOrder.graphql. You can edit the file by eliminating unnecessary fields, or replace with other GraphQL queries/mutations. If you want to know each field of order query, or other APIs, please find Buy with Prime API reference.

• Extract order_id from the event payload
• Call order with the order_id to get all information of a single order.
• Store the response in S3 in the format of timestamp.

1. Clone this repository.
2. Update .env
   • CLIENT_ID and CLIENT_SECRET: When you have your client ID after onboarding process completed. (Optional)
   • S3_BUCKET_ARN
   • EVENT_BUS_ARN - your Buy with Prime Accelerator's EventBridge ARN.
   • MOCK_BWP_API - your Buy with Prime Accelerator's Appsync endpoint.
   • AWS_REGION - Your AWS region.
3. Run cdk commands.

cdk bootstrap
cdk deploy

You can generate a mock Buy with Prime event by calling Buy with Prime accelerator's event API. The mock event API endpoint can be found in the Amazon API Gateway under the name Event-api.

• ORDER_PLACED, ORDER_UPDATED, REFUND_SUCCESS.

curl --location --request POST '{Mock_Event_API_endpoint/prod}/put-event/order?event-type=order_placed'

curl --location --request POST '{Mock_Event_API_endpoint/prod}/put-event/order?event-type=order_updated'

curl --location --request POST '{Mock_Event_API_endpoint/prod}/put-event/order?event-type=refund_success'

curl --location --request POST '{Mock_Event_API_endpoint/prod}/put-event/buyability?event-type=buyability'

curl --location --request POST '{Mock_Event_API_endpoint/prod}/put-event/inventory?event-type=inventory'

This event accelerator has two custom rules to forward events to different targets based on the event types.

The CDK has sample event pattern to filter Buy with Prime event types. You can update the rules in lib/cdk-stack.ts.

    eventPattern: {
    "detail": {
        "eventType": ["ORDER_PLACED", "ORDER_UPDATED", "REFUND_SUCCESS"]
    }
    },

    eventPattern: {
    "detailType": ["santos.buyability.status.change", "INVENTORY_AVAILABILITY_CHANGED"]
    },

The lambda function looks at the value of detail-type in the event payload to determine the event type. If the value is INVENTORY_AVAILABILITY_CHANGED, it extracts inventoryItemId from the event payload, and queries inventory with it. Or, if the value is santos.buyability.status.change, it extracts itemId instead, and queries buyability.

The inventory query provides the buyable quantity, as well as the external ID and SKU of the mapping product. The following is an example of an inventory query response.

{
    "data": {
        "inventoryItem": {
            "buyableQuantity": {
                "amount": 10,
                "unit": "DAYS"
            },
            "inventoryItemId": "w6ibvyca8tmh83",
            "mappingProduct": {
                "externalId": "93c711ed-517d-4e45-873f-b615dc97dd6a",
                "id": "w6ibvyca8tmh83",
                "isPrimeIntended": true,
                "sku": "8f72b379-b669-46a5-a37d-7b2e07b227a4",
                "url": "https://testurl"
            }
        }
    }
}

The buyability query, on the other hand, takes a variety of arguments, including ID, external ID, SKU, and mSKU, and returns a buyable status. This sample shows an example of using an ID. The following is an example of a buyability query response.

{
    "data": {
        "buyability": {
            "status": "true"
        }
    }
}

Unlike REST, GraphQL will return a response with code 200, regardless of whether or not there was an error in the call. A 200 in GraphQL simply means that the endpoint is available and you successfully made a call. Instead of using specific error codes, GraphQL reports errors by adding error blocks. This allows for much more granual error reporting than generic response codes. For more on Errors in GraphQL, see the GraphQL spec documentation here.

This Event accelerator is designed to handle GraphQL errors in these scenarios:

• The response status is not 200. This means the endpoint is not available
• The response body contains an "errors" section. This means the call was sent successfully, but there was an error during execution

    ...
    if response.status != 200 or 'errors' in str(response_data): // detect errors
        print("response", response.status, response_text)
    else:
        ...

This is an example response to an Order query when the Order object doesn't exist. The HTTP response status would still be 200. However, the body of the response contains details of the errors. You should consider these cases when building out your GraphQL error handling.

response 200 
{
    "data": {
        "order": null
    },
    "errors": [
        {
            "path": [
                "order"
            ],
            "data": null,
            "errorType": "MappingTemplate",
            "errorInfo": null,
            "locations": [
                {
                    "line": 2,
                    "column": 3,
                    "sourceName": null
                }
            ],
            "message": "Template transformation yielded an empty response."
        }
    ]
}

Of course, you should also consider errors where the code is not 200. Find more information about errors by code in Buy with prime GraphQL API error codes.

• This sample code is designed based on Buy with Prime Accelerator, not using neither production events or APIs.
• Buy with Prime Accelerator uses static token, so this sample does not contain authentication logic to store or refresh tokens.

By running cdk command, you can clear most of the resources.

cdk destroy

However, you need to manually delete these resources.

• Amazon S3 bucket: If the bucket is not empty, cdk destroy cannot delete the bucket. You need to empty the bucket before running cdk destory, or manually delete the bucket.
• AWS Lambda Log groups: The CDK stack sets the log retention period to one month. If you want to delete a log group before this period, you can delete the log group manually. Go to Amazon CloudWatch > Logs > Log groups and filter for EventAcceleratorStack to find the log group.

• Buy with Prime API reference
• Buy with Prime Event Integration Guide
• Buy with prime GraphQL API error codes