brick-traces

A simple wrapper to collect logs and metrics for fraud prevention.

brick-traces is a comprehensive utility library designed to help organizations monitor their fraud prevention providers and optimize workflows. By integrating with the Brick Traces API, customers can collect logs, metrics, and operational data, gaining actionable insights into their processes. Supporting popular HTTP clients such as Axios, Fetch, and more, it seamlessly captures detailed request and response data, enabling businesses to improve decision-making, streamline fraud prevention strategies, and achieve greater operational efficiency.

Features

• HTTP Request Wrapping: Automatically trace HTTP requests and log their metadata.
• Trace Data Submission: Send detailed metrics to the Brick Traces API for analysis.
• Customizable Configurations: Easily include additional metadata and tags.
• Support for Popular HTTP Clients: Works seamlessly with Axios, Fetch, Got, and more.
• Error Handling: Collect metrics for failed requests without interrupting the flow.

Installation

Install the library via npm:

npm install brick-traces

Usage

1. Wrapping an HTTP Request

Use the wrapperHttp function to intercept an HTTP request, collect metrics, and optionally send them to the Brick Traces API.

Example with Axios:

import axios from "axios";
import { wrapperHttp } from "brick-traces";

(async () => {
  const response = await wrapperHttp(
    axios.get("https://jsonplaceholder.typicode.com/posts/1"),
    {
      accessKey: "your-brick-access-key",
      secret: "your-brick-secret",
      clientId: "your-client-id",
      document: "111.111.111-11",
      name: "Fetch Post",
      tags: ["example", "axios"],
      metadata: { purpose: "testing" },
      cost: 10,
      provider: "example-provider",
    }
  );

  console.log("Response:", response);
})();

Configuration Options:

• clientId (string): Identifier for the client making the request.
• accessKey (string, optional): Your Brick Traces access key.
• secret (string, optional): Your Brick Traces secret.
• name (string, optional): A name for the trace.
• document (string, optional): A unique identifier for the trace.
• tags (array, optional): Tags associated with the trace.
• metadata (object, optional): Additional metadata for the request.
• cost (number, optional): The cost of the operation.
• providerInternalId (string, optional): The provider's internal identifier.
• provider (string, optional): The name of the provider.

2. Environment Variable

Set the BRICK_TRACES_ACCESS_KEY and the BRICK_TRACES_SECRET to authenticate and start collecting metrics.

Example .env file:

BRICK_TRACES_ACCESS_KEY=<YOUR_ACCESS_KEY>
BRICK_TRACES_SECRET=<YOUR_SECRET>

3. Sending Data to Brick Traces

When using the wrapperHttp function with an accessKey and secret, the following data is sent asynchronously to the Brick Traces API:

Trace Data:

{
  "accessKey": "your-brick-access-key",
  "secret": "your-brick-secret",
  "trace": {
    "tags": ["example", "axios"],
    "clientId": "your-client-id",
    "document": "111.111.111-11",
    "name": "Fetch Post"
  },
  "request": {
    "metadata": { "purpose": "testing" },
    "requestedAt": "2025-01-12T12:00:00.000Z",
    "cost": 10,
    "provider": "example-provider",
    "elapsedTime": 123,
    "providerInternalId": "internal-id",
    "statusCode": 200,
    "responseBody": "{\"id\": 1, \"title\": \"Post Title\"}"
  },
  "timestamp": "2025-01-12T12:00:01.000Z"
}

4. Decisions

The decide function allows you to log and send decisions based on evaluation criteria to the Brick Traces API.

Example:

import { decide } from "brick-traces";

const decision = {
  decisionId: "133f0236-44b9-4a50-8aa5-488d6097fce9",
};

const searchParams = {
  clientId: "12345",
  document: "67890",
};

decide(decision, searchParams, { accessKey: "your-access-key", secret: "your-credential-secret" });

Function Details:

• decision: Object containing the decision details (e.g., outcome and reason).
  • decisionId (string, optional): Referes to a decision already registered at Brick's platform.
  • name (string, optional): If decisionId is empty, you can pass your own name of the decision.
  • variant (string, optional): If name exists, you must send a variant that can be one of ['APPROVAL', 'REFUSAL', 'MANUAL'].
• searchParams: Object containing search identifiers (e.g., clientId, document).
• config: Object with optional parameters to authenticate the request.

This data is sent to the /decision endpoint of the Brick Traces API.

5. Registering Variables

The registerVariables function allows you to send contextual variables for a specific search to the Brick Traces API.

Example:

import { registerVariables } from "brick-traces";

const variables = [
  { name: "transaction_amount", value: 150.75 },
  { name: "user_country", value: "US" },
];

const searchParams = {
  clientId: "12345",
  document: "67890",
};

registerVariables(variables, searchParams, { apiKey: "your-brick-api-key" });

Function Details:

• variables: Array of name-value pairs to register.
• searchParams: Object containing search identifiers.
• config: Object with optional apiKey to authenticate the request.

This data is sent to the /variable endpoint of the Brick Traces API.

Error Handling

Even if the request fails, brick-traces collects error details and sends them to the Brick Traces API.

Example:

try {
  await wrapperHttp(
    axios.get("https://jsonplaceholder.typicode.com/posts/invalid"),
    {
      accessKey: "your-access-key",
      secret: "your-credential-secret",
      clientId: "your-client-id",
      name: "Fetch Invalid Post",
    }
  );
} catch (error) {
  console.error("Request failed:", error);
}

Error payload:

{
  "statusCode": 404,
  "responseBody": "{\"error\": \"Not Found\"}"
}

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

For questions or support, reach out to:

• Brick Team
• Website: brick.com
• Email: support@brick.com