MonetizationOS

https://docs.monetizationos.com
Admin
MonetizationOS is a platform that provides comprehensive tools and services for managing and...
Tokens:70,432
Snippets:692
Trust Score:5.5
Update:7 months ago
Show doc for...
Tokens:
Raw
### Get Linked Sources Example (JavaScript)

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/ReadIdentityLinksWorkflowUtils

Example demonstrating how to use the getLinkedSources function to retrieve all source links associated with a target identity. It requires a user identifier object.

```javascript
const sources = await utils.identity.getLinkedSources({ identifier: 'member_1234', userType: 'authenticated' });
```

--------------------------------

### Example: Get Bucket Value in TypeScript

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/ReadonlyBucketWorkflowUtils

An example demonstrating how to use the utils.buckets.get() method in TypeScript to retrieve a value, such as 'all-sites' from the 'bot-config' bucket, and assigning it to a 'theme' constant.

```typescript
const theme = await utils.buckets.get('bot-config', 'all-sites')
```

--------------------------------

### Hello World Workflow Example (TypeScript)

Source: https://docs.monetizationos.com/docs/guides/orchestration/endpoints

A basic example of a MonetizationOS endpoint workflow that returns a 'hello world' response. This workflow is written in TypeScript and demonstrates the basic structure of an endpoint function, including access to request data, environment variables, and utility functions.

```typescript
const workflow: EndpointWorkflow = async ({ request, env, utils }) => {
  return new Response("hello world");
};

export default workflow;
```

--------------------------------

### Dynamic Provisioning Workflow Example

Source: https://docs.monetizationos.com/docs/api-reference/workflows/dynamic-provisioning-workflows

An example of a Dynamic Provisioning workflow that assigns plans based on user identity and JWT claims.

```APIDOC
## POST /workflows/provisioning

### Description
Dynamically assign Plans to users at decision time based on request context and business logic. Dynamic Provisioning workflows enable automatic plan assignment based on user identity, request context, JWT claims, geolocation, and other runtime data.

### Method
POST

### Endpoint
/workflows/provisioning

### Parameters
#### Request Body
- **identity** (WorkflowIdentity) - Required - User identity information.
- **resource** (WorkflowResource) - Required - Resource information.
- **customerData** (WorkflowCustomerData) - Optional - Customer data.
- **context** (WorkflowContext) - Optional - Request context.
- **env** (WorkflowEnv) - Optional - Environment variables.
- **utils** (ReadonlyWorkflowUtils) - Required - Read-only utility functions.

### Request Example
```javascript
const workflow: ProvisioningWorkflow = async ({ identity }: ProvisioningWorkflowArgs) => {
    if (identity.jwtClaims.premium) {
        return ["premium"];
    }

    if (identity.userType === "authenticated") {
        return ["registered"];
    }

    return ["anonymous"];
};

export default workflow;
```

### Response
#### Success Response (200)
- **plans** (string[]) - An array of plan slugs to assign to the user or session. Returns an empty array `[]` if no plans should be dynamically assigned.
```

--------------------------------

### Get Linked Targets Example (JavaScript)

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/ReadIdentityLinksWorkflowUtils

Example demonstrating how to use the getLinkedTargets function to retrieve all target links associated with a source identity. It requires a user identifier object.

```javascript
const targets = await utils.identity.getLinkedTargets({ identifier: 'member_1234', userType: 'authenticated' });
```

--------------------------------

### Surface Workflow Example

Source: https://docs.monetizationos.com/docs/getting-started/hello-world/1-surface

Example of a basic Surface Workflow written in TypeScript that adds a custom property to the surface decision response.

```APIDOC
## Surface Workflow Example

### Description
This TypeScript code defines a simple Surface Workflow that adds a custom property `userMessage` with the value "Hello, World!" to the response of a surface decision.

### Method
N/A (This is a workflow definition, not an API endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (when used with POST /api/v1/surface-decisions)
- **surfaceBehavior.properties.userMessage** (string) - The custom message defined in the workflow.

#### Response Example (showing the added property)
```json
{
    "status": "success",
    "eventId": "0c7a44d0-41db-4c95-b7fd-3b937b57a1da",
    "identity": {
        "authType": "anonymous",
        "identifier": "test",
        "isAuthenticated": false,
        "jwtClaims": {}
    },
    "customer": {
        "isCustomer": false,
        "hasProducts": false,
        "customerIdentifiers": []
    },
    "features": {},
    "surfaceBehavior": {
        "properties": {
            "userMessage": "Hello, World!"
        }
    },
    "componentsSkipped": false,
    "componentBehaviors": {}
}
```
```

--------------------------------

### Dynamic Provisioning Workflow

Source: https://docs.monetizationos.com/docs/getting-started/hello-world/4-dynamic-provisioning

Example of a dynamic provisioning workflow that assigns a 'premium' plan based on the 'premium' claim in the JWT token.

```APIDOC
## Dynamic Provisioning Workflow

### Description
This workflow dynamically assigns plans based on JWT claims. It checks for a 'premium' claim in the JWT token and assigns the 'premium' plan if the claim is true.

### Method
N/A (This is a workflow definition, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **Array of plan IDs** (string[]) - Returns an array of plan IDs to be provisioned for the user.

#### Response Example
```javascript
const workflow: ProvisioningWorkflow = async ({ identity }) => {
    // Assign premium if provided in JWT claims
    return identity.jwtClaims.premium ? ["premium"] : [];
};

export default workflow;
```
```

--------------------------------

### Custom Instructions for Offer Redemption (JSON)

Source: https://docs.monetizationos.com/docs/guides/offers/add-offers/configure-redemption-methods

Example of custom instructions for offer redemption, used for non-Stripe payment providers or custom actions. This JSON object is returned in the API response to guide frontend actions.

```json
{
  "redirectTo": "/register"
}
```

--------------------------------

### Feature Workflow Example

Source: https://docs.monetizationos.com/docs/api-reference/workflows/feature-workflows

An example of a Feature Workflow implementation that dynamically enables or disables a feature based on whether the request is from a verified bot.

```APIDOC
## Feature Workflow

### Description
Dynamically override feature property values based on custom logic. Feature workflows let you pull property values from external sources (e.g. JWT claims, third-party APIs, etc.) instead of relying solely on plan-based provisioning.

### Method
Asynchronous Function (executed within MonetizationOS)

### Endpoint
N/A (Internal execution within MonetizationOS)

### Arguments
`context`: `FeatureWorkflowArgs` - Provides access to request context, including `isVerifiedBotRequest`.

### Return Type
`FeatureWorkflowResult`: `Record<string, WorkflowOverrideProperty>` - An object where keys are feature property slugs and values define the override.

### Request Example
```javascript
const workflow: FeatureWorkflow = async ({ context }: FeatureWorkflowArgs): Promise<FeatureWorkflowResult> => {
    return {
        enabled: context.isVerifiedBotRequest ? "off" : "on",
    };
};

export default workflow;
```

### Response
#### Success Response (Implicit)
- **enabled** (`string`) - Either 'on' or 'off', indicating the feature's state.

#### Response Example
```json
{
  "enabled": "on"
}
```

### Property Override Rules
- Only properties defined on the feature can be overridden.
- Overriding property type (e.g. returning a string for a number property) is not allowed.
- Overrides set `isFallback: false`, indicating the value is not a default.
- Returning an empty object `{}` leaves all properties unchanged.
```

--------------------------------

### Example: Incrementing Meter Counter

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/WorkflowConsumableMeter

Provides an example of how to use the incrementCounter method to increase a meter's counter by a specified number of units.

```javascript
await features.myFeature.incrementCounter({ units: 1 })
```

--------------------------------

### Endpoint Workflow Example

Source: https://docs.monetizationos.com/docs/api-reference/workflows/endpoint-workflows

Example of an Endpoint Workflow that handles incoming HTTP requests and returns a custom response.

```APIDOC
## POST /websites/monetizationos/workflows/endpoint

### Description
Handles incoming HTTP requests with custom logic. Endpoint workflows allow you to create custom API endpoints backed by your own business logic, with access to identity, integrations, and offer engine utilities.

### Method
POST

### Endpoint
/websites/monetizationos/workflows/endpoint

### Parameters
#### Query Parameters
- **request** (object) - Required - The incoming HTTP request object.
- **ctx** (object) - Required - Context object containing utilities for integrations, offer engine, identity observability, and general workflow utilities.
- **env** (object) - Required - Environment variables for the workflow.

### Request Example
```javascript
const workflow: EndpointWorkflow = async ({ request }: EndpointWorkflowArgs): Promise<EndpointWorkflowResult> => {
    const path = new URL(request.url).pathname;
    return new Response(`hello, ${path}`);
};

export default workflow;
```

### Response
#### Success Response (200)
- **Response** (object) - A standard Web API `Response` object with custom status, headers, and body.

#### Response Example
```javascript
// Example using standard Response constructor
new Response('Custom response body', { status: 200, headers: { 'Content-Type': 'text/plain' } });

// Example using Response.json()
Response.json({ message: 'Success' });

// Example using Response.error()
Response.error();

// Example using Response.redirect()
Response.redirect('/new-url');
```

### Access Levels
Endpoints can be configured with the following access levels:
- **No Key:** No authentication required.
- **Public Key:** Requires public API key authentication.
- **Secret Key:** Requires API key authentication via `X-MOS-Key` header.

Access level is configured in the endpoint settings, not in the workflow code.
```

--------------------------------

### AccessCheckRequest Example

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/WebscaleApiDataModels

An example JSON payload for an AccessCheckRequest, demonstrating the structure for identity and resource.

```json
{
     "identity": {
       "userIdentifier": "user_12345"
     },
     "resource": {
       "id": "article_abc123"
     }
     }
```

--------------------------------

### Dynamic Provisioning Workflow Example (JavaScript)

Source: https://docs.monetizationos.com/docs/concepts/plans

This code snippet demonstrates a dynamic provisioning workflow in JavaScript. It evaluates custom business logic at runtime to assign plans based on user claims, such as organization size. This allows for real-time plan assignment based on specific criteria.

```javascript
// evaluated at runtime
if (claims.orgSize > 50)
return 'Enterprise'
```

--------------------------------

### SurfaceDecisionRequest Example (JSON)

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/WebscaleApiDataModels

An example of a SurfaceDecisionRequest payload, demonstrating the structure for requesting decisions for a 'website' surface with a specific user identifier and resource.

```json
{
  "surfaceSlug": "website",
  "identity": {
    "userIdentifier": "user_12345"
  },
  "resource": {
    "id": "article_abc123"
  }
}
```

--------------------------------

### Replace Range Example (JavaScript)

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/WebContentSurfaceBehavior

Demonstrates how to use the 'replaceRange' property to modify a specific section of content within a component. It shows examples of replacing content based on a marker, replacing content with new elements, and replacing content between two markers.

```javascript
{
  fromMarker: 'p:nth-child(2)'
}
```

```javascript
{
  fromMarker: 'p:nth-child(2)',
  replaceWith: [{type: 'html', content: '<h1>Content Removed</h1>'}]
}
```

```javascript
{
  fromMarker: '.title',
  toMarker: 'img',
  replaceWith: [{type: 'html', content: '<h1>Content Removed</h1>'}]
}
```

--------------------------------

### Surface Workflow Usage

Source: https://docs.monetizationos.com/docs/api-reference/workflows/surface-workflows

Example of how to define and export a Surface Workflow function.

```APIDOC
## POST /websites/monetizationos/surface-workflows

### Description
This endpoint allows you to define and execute custom business logic for controlling Surface behavior. Surface workflows run before child Component workflows and can modify properties and HTTP responses.

### Method
POST

### Endpoint
/websites/monetizationos/surface-workflows

### Parameters
#### Query Parameters
- **identity** (WorkflowIdentity) - Required - Information about the user or entity requesting the surface decision.
- **resource** (WorkflowResource) - Required - Details about the resource associated with the surface decision.
- **customerData** (WorkflowCustomerData) - Optional - Additional data about the customer.
- **context** (WorkflowContext) - Optional - Contextual information for the workflow execution.
- **features** (Record<string, Record<string, SurfaceWorkflowProperty>>) - Optional - Feature flags and their configurations.
- **utils** (WorkflowOfferEngineUtils & WorkflowUtils) - Optional - Utility functions for offer engine and general use.
- **env** (WorkflowEnv) - Optional - Environment variables for the workflow.

#### Request Body
This endpoint does not typically accept a request body for defining the workflow itself. The workflow logic is defined in the code as shown in the example.

### Request Example
```javascript
// Example of defining a Surface Workflow
const workflow = async ({ identity, resource, features }) => {
    return {
        properties: {
            userMessage: `Hello, ${identity.identifier}`,
            hasWidgetAccess: features.widget.enabled,
            resourceId: resource.id,
        },
        http: {
            status: 200,
            headers: {
                "X-Custom-Greeting": `Welcome, ${identity.identifier}`,
            },
            body: JSON.stringify({
                message: `Hello from Surface Workflow, ${identity.identifier}`,
            }),
        },
    };
};

export default workflow;
```

### Response
#### Success Response (200)
- **properties** (Record<string, unknown>) - Optional - Computed values to be used by the surface or passed to child workflows.
- **http** (SetHttpResponse | ModifyHttpResponse) - Optional - An object to override or modify the HTTP response (status, headers, body).

#### Response Example
```json
{
  "properties": {
    "userMessage": "Hello, user123",
    "hasWidgetAccess": true,
    "resourceId": "res456"
  },
  "http": {
    "status": 200,
    "headers": {
      "X-Custom-Greeting": "Welcome, user123"
    },
    "body": "{\"message\": \"Hello from Surface Workflow, user123!\"}"
  }
}
```
```

--------------------------------

### Example MonetizationOS Surface Decision Response

Source: https://docs.monetizationos.com/docs/getting-started/hello-world/2-features-plans

This JSON snippet illustrates a typical response from a MonetizationOS Surface decision, showcasing the structure of 'features' including feature IDs, slugs, and their associated properties with their types and values. It demonstrates how features and their properties are represented after initial creation.

```json
{
    "...": "...",
    "features": {
        "widget": {
            "featureId": "feat_abcd1234",
            "featureSlug": "widget",
            "properties": {
                "premium": {
                    "type": "boolean",
                    "value": false,
                    "isFallback": true
                },
                "enabled": {
                    "counterId": "default:feat_abcd1234.enabled",
                    "type": "meterable",
                    "hasAccess": false,
                    "isFallback": true
                }
            }
        }
    },
    "...": "..."
}
```

--------------------------------

### Update Usage Counters (Go)

Source: https://docs.monetizationos.com/docs/api-reference/webscale/counter-updates/updateCounters

Example of updating usage counters using Go's net/http package. This demonstrates making a POST request with a JSON body to the MonetizationOS API for counter updates.

```Go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://api.monetizationos.com/api/v1/counter-updates"

	requestBody, err := json.Marshal(map[string]interface{}{
		"identity": map[string]string{
			"anonymousIdentifier": "anon_session_789"
		},
		"counterId": "default:feat_123456.requests",
		"update": 1
	})
	if err != nil {
		fmt.Println("Error marshaling JSON:", err)
		return
	}

	resp, err := http.Post(url, "application/json", bytes.NewBuffer(requestBody))
	if err != nil {
		fmt.Println("Error sending request:", err)
		return
	}

	defer resp.Body.Close()

	var result map[string]interface{}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		fmt.Println("Error decoding response:", err)
		return
	}

	fmt.Println(result)
}
```

--------------------------------

### Retrieve Value from Bucket using get()

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/ReadonlyBucketWorkflowUtils

The get() method retrieves a value from a named bucket using a specified key. It supports generic type inference for the expected return value and accepts optional configuration like 'crossBrand'. Keys must be non-empty strings up to 128 characters.

```typescript
get<T>(
   bucketSlug,
   key,
options?): Promise<T | null>;
```

--------------------------------

### Example JWT Surface Decision Response (JSON)

Source: https://docs.monetizationos.com/docs/getting-started/hello-world/4-dynamic-provisioning

This JSON object represents a typical response from a JWT Surface decision request. It includes details about feature enablement, access status, consumed units, and user properties related to widget access and premium features.

```json
{
    "enabled": {
        "counterId": "default:feat_abcd1234.enabled",
        "type": "meterable",
        "hasAccess": false,
        "consumedUnits": 3,
        "remainingUnits": 0,
        "totalUnits": 3,
        "uniqueResources": false,
        "resourceIdUsed": false,
        "periodStart": "Thu, 01 Jan 1970 00:00:00 GMT",
        "hasAccess": true,
        "isFallback": false
    },
    "surfaceBehavior": {
        "properties": {
            "userMessage": "Hello, test+9@example.com",
            "isAuthenticated": true,
            "widgetAccess": false,
            "premiumWidgets": false,
            "remainingWidgets": 0,
            "widgetAccess": true,
            "premiumWidgets": true
        }
    }
}
```

--------------------------------

### Make First Surface Decision with cURL

Source: https://docs.monetizationos.com/docs/getting-started/hello-world/1-surface

This cURL command makes a POST request to the MonetizationOS API to get a decision for a specific surface. It requires an API key and the surface slug. The response includes status, event ID, identity, customer information, and surface/component behaviors.

```shell
curl -X POST https://api.monetizationos.com/api/v1/surface-decisions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "surfaceSlug": "$SURFACE_SLUG",
  "identity": {
    "anonymousIdentifier": "test"
  }
}'
```

--------------------------------

### Update Usage Counters (C#)

Source: https://docs.monetizationos.com/docs/api-reference/webscale/counter-updates/updateCounters

Example of updating usage counters using C#'s HttpClient. This shows how to construct and send a JSON payload to the /api/v1/counter-updates endpoint for tracking user activity.

```C#
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

public class CounterUpdate {

    public static async Task Main(string[] args) {
        using (var client = new HttpClient()) {
            var url = "https://api.monetizationos.com/api/v1/counter-updates";

            var requestBody = new {
                identity = new {
                    anonymousIdentifier = "anon_session_789"
                },
                counterId = "default:feat_123456.requests",
                update = 1
            };

            var json = JsonConvert.SerializeObject(requestBody);
            var content = new StringContent(json, Encoding.UTF8, "application/json");

            var response = await client.PostAsync(url, content);
            var responseString = await response.Content.ReadAsStringAsync();

            Console.WriteLine(responseString);
        }
    }
}
```

--------------------------------

### Define Dynamic Provisioning Workflow (TypeScript)

Source: https://docs.monetizationos.com/docs/api-reference/workflows/dynamic-provisioning-workflows

This example demonstrates how to define a dynamic provisioning workflow in TypeScript. The workflow takes an identity object and returns an array of plan slugs based on JWT claims or user type. It requires the ProvisioningWorkflow and ProvisioningWorkflowArgs types.

```typescript
const workflow: ProvisioningWorkflow = async ({ identity }: ProvisioningWorkflowArgs) => {
    if (identity.jwtClaims.premium) {
        return ["premium"];
    }

    if (identity.userType === "authenticated") {
        return ["registered"];
    }

    return ["anonymous"];
};

export default workflow;
```

--------------------------------

### Example Usage of testGroup100 for User Segmentation (JavaScript)

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/ActionWorkflowIdentity

Provides an example of how to use the testGroup100 property from an identity object to conditionally assign users to different plans (e.g., 'plan-a' or 'plan-b'). This demonstrates practical application for A/B testing or feature rollout.

```javascript
return identity.testGroup100 < 50 ? ['plan-a'] : ['plan-b']; 
```

--------------------------------

### Update Usage Counters (Java)

Source: https://docs.monetizationos.com/docs/api-reference/webscale/counter-updates/updateCounters

Example of updating usage counters using Java's HttpClient. This demonstrates making a POST request with a JSON body to the MonetizationOS API for counter updates.

```Java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.HashMap;
import java.util.Map;

public class CounterUpdate {

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        String url = "https://api.monetizationos.com/api/v1/counter-updates";

        Map<String, Object> identity = new HashMap<>();
        identity.put("anonymousIdentifier", "anon_session_789");

        Map<String, Object> requestBodyMap = new HashMap<>();
        requestBodyMap.put("identity", identity);
        requestBodyMap.put("counterId", "default:feat_123456.requests");
        requestBodyMap.put("update", 1);

        String jsonBody = new com.fasterxml.jackson.databind.ObjectMapper().writeValueAsString(requestBodyMap);

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}
```

--------------------------------

### ReadonlyBucketWorkflowUtils get()

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/ReadonlyBucketWorkflowUtils

Retrieves a value from a named bucket using its key. Supports custom data options like 'crossBrand'.

```APIDOC
## GET /websites/monetizationos/buckets/{bucketSlug}/{key}

### Description
Retrieve a value from a named bucket by key. Keys must be non-empty strings of up to 128 characters. If the value was written with the 'crossBrand' option, that must be passed here too.

### Method
GET

### Endpoint
`/websites/monetizationos/buckets/{bucketSlug}/{key}`

### Parameters
#### Path Parameters
- **bucketSlug** (string) - Required - The name of the bucket to retrieve the value from.
- **key** (string) - Required - The key to retrieve. Must be a non-empty string of up to 128 characters.

#### Query Parameters
- **crossBrand** (boolean) - Optional - Indicates if the value was written with the 'crossBrand' option.

### Request Example
```ts
const theme = await utils.buckets.get('bot-config', 'all-sites')
```

### Response
#### Success Response (200)
- **T** (any) - The stored value, or null if not found.

#### Response Example
```json
{
  "value": "example_data"
}
```
```

--------------------------------

### Perform Access Check (cURL)

Source: https://docs.monetizationos.com/docs/api-reference/webscale/access-checks/performAccessCheck

Example of performing an access check for an anonymous user using cURL. This demonstrates the POST request to the /api/v1/access-checks endpoint with the necessary JSON body.

```curl
curl -X POST "https://api.monetizationos.com/api/v1/access-checks" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": {
      "anonymousIdentifier": "anon_session_789"
    },
    "resource": {
      "id": "article_xyz"
    }
  }'
```

--------------------------------

### Update Usage Counters (Python)

Source: https://docs.monetizationos.com/docs/api-reference/webscale/counter-updates/updateCounters

Example of updating usage counters using Python's requests library. This shows how to send a POST request with a JSON payload to the /api/v1/counter-updates endpoint.

```Python
import requests
import json

url = "https://api.monetizationos.com/api/v1/counter-updates"

payload = {
    "identity": {
        "anonymousIdentifier": "anon_session_789"
    },
    "counterId": "default:feat_123456.requests",
    "update": 1
}

headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))

print(response.json())
```

--------------------------------

### Action Workflow Usage

Source: https://docs.monetizationos.com/docs/api-reference/workflows/action-workflows

Example of how to define an Action Workflow in TypeScript. This workflow sends a PUT request to a dummy JSON API to update user plans.

```APIDOC
## Action Workflow Usage

### Description
This code snippet demonstrates the definition of an asynchronous Action Workflow using TypeScript. The workflow takes `identity` and `payload` as arguments and performs an asynchronous operation, such as updating user plans via an external API.

### Method
N/A (This is a code definition, not an HTTP request)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```typescript
const workflow: ActionWorkflow = async ({ identity, payload }: ActionWorkflowArgs) => {
    await fetch(`https://dummyjson.com/users/${identity?.identifier}`, {
        method: "PUT",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
            newPlans: payload,
        }),
    });

    return {
        status: "success",
    };
};

export default workflow;
```

### Response
#### Success Response (200)
N/A (Workflow execution result is for observability)

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Update Usage Counters (JavaScript)

Source: https://docs.monetizationos.com/docs/api-reference/webscale/counter-updates/updateCounters

Example of updating usage counters using JavaScript's Fetch API. This shows how to construct and send a JSON payload to the /api/v1/counter-updates endpoint for tracking user activity.

```JavaScript
fetch("https://api.monetizationos.com/api/v1/counter-updates", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "identity": {
      "anonymousIdentifier": "anon_session_789"
    },
    "counterId": "default:feat_123456.requests",
    "update": 1
  })
})
.then(response => response.json())
.then(data => console.log(data));
```

--------------------------------

### Example Usage of testGroup100 (JavaScript)

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/WorkflowIdentity

Demonstrates how to use the testGroup100 property to assign users to different test groups. This property is a number between 0 and 99 derived from a hash of the user's identifier, ensuring consistent group assignment.

```javascript
return identity.testGroup100 < 50 ? ['plan-a'] : ['plan-b'];
```

--------------------------------

### Property Definition: periodStart

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/WorkflowMeterablePropertyEvaluation

Defines the 'periodStart' property for WorkflowMeterablePropertyEvaluation. This optional string represents the start time of the current consumption period. It is used in conjunction with other properties to calculate remaining or consumed units over time.

```plaintext
optional periodStart: string;
```

--------------------------------

### Update Usage Counters (cURL)

Source: https://docs.monetizationos.com/docs/api-reference/webscale/counter-updates/updateCounters

Example of updating usage counters using cURL. This demonstrates sending a POST request to the /api/v1/counter-updates endpoint with an anonymous identifier, counter ID, and update value.

```cURL
curl -X POST "https://api.monetizationos.com/api/v1/counter-updates" \
  -H "Content-Type: application/json" \
  -d '{ \
    "identity": { \
      "anonymousIdentifier": "anon_session_789" \
    }, \
    "counterId": "default:feat_123456.requests", \
    "update": 1 \
  }'
```

--------------------------------

### Access Check Response - User Has Access (JSON)

Source: https://docs.monetizationos.com/docs/api-reference/webscale/access-checks/performAccessCheck

Example JSON response indicating a user has access to features. It includes status, event ID, identity details, customer information, and feature properties like enabled status and usage quotas.

```json
{
  "status": "success",
  "eventId": "c918c19e-b782-4c2f-93c0-8a5f94c0a1b5",
  "identity": {
    "authType": "provided",
    "isAuthenticated": true,
    "identifier": "user_12345"
  },
  "customer": {
    "isCustomer": true,
    "hasProducts": true,
    "customerIdentifiers": [
      "user_12345",
      "stripe_cus_abc123"
    ]
  },
  "features": {
    "article": {
      "featureId": "feat_123456",
      "featureSlug": "article",
      "properties": {
        "enabled": {
          "type": "meterable",
          "counterId": "default:feat_123456.enabled",
          "hasAccess": true,
          "consumedUnits": 3,
          "remainingUnits": 2,
          "totalUnits": 5,
          "periodStart": "2025-07-01T00:00:00Z",
          "uniqueResources": false,
          "resourceIdUsed": false,
          "consumedInRequest": false,
          "isFallback": false
        },
        "ads": {
          "type": "boolean",
          "value": false,
          "isFallback": true
        }
      }
    }
  }
}
```

--------------------------------

### Access Surface Properties in Component Workflow (TypeScript)

Source: https://docs.monetizationos.com/docs/api-reference/workflows/component-workflows

This TypeScript example demonstrates how a component workflow accesses properties passed from its parent surface workflow. The `surfaceProperties` argument contains values computed by the parent, allowing for dynamic customization of the component's behavior and content.

```typescript
// Parent surface workflow
const surfaceWorkflow: SurfaceWorkflow = async ({ identity }) => {
    return {
        properties: {
            theme: "dark",
            userId: identity.identifier,
        },
    };
};

// Component workflow - receives surface properties
const componentWorkflow: SurfaceWorkflow = async ({ surfaceProperties }) => {
    const theme = surfaceProperties?.theme; // "dark"
    const userId = surfaceProperties?.userId; // user identifier
    // ...
};
```

--------------------------------

### Make a Registered Surface Decision (cURL)

Source: https://docs.monetizationos.com/docs/getting-started/hello-world/2-features-plans

This cURL command demonstrates how to make a Surface decision for a registered user by providing a `userIdentifier`. It requires an API key and a surface slug. The response will reflect the user's plan assignments and feature access.

```bash
curl -X POST https://api.monetizationos.com/api/v1/surface-decisions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "surfaceSlug": "$SURFACE_SLUG",
  "identity": {
    "userIdentifier": "test@example.com"
  }
}'
```

--------------------------------

### POST /api/v1/surface-decisions

Source: https://docs.monetizationos.com/docs/getting-started/hello-world/4-dynamic-provisioning

This endpoint is used to make a surface decision, which can now leverage JWT tokens for user identification and authentication.

```APIDOC
## POST /api/v1/surface-decisions

### Description
This endpoint makes a surface decision, allowing for dynamic plan provisioning based on JWT claims.

### Method
POST

### Endpoint
/api/v1/surface-decisions

### Parameters
#### Query Parameters
None

#### Request Body
- **surfaceSlug** (string) - Required - The slug of the surface to make a decision for.
- **identity** (object) - Required - The identity of the user.
  - **userJwt** (string) - Required - The JWT token for the user.

### Request Example
```json
{
  "surfaceSlug": "$SURFACE_SLUG",
  "identity": {
    "userJwt": "$JWT_TOKEN"
  }
}
```

### Response
#### Success Response (200)
- **identity** (object) - Information about the user's identity, including authentication details and JWT claims.
  - **authType** (string) - The authentication type used (e.g., 'jwt').
  - **identifier** (string) - The user's identifier (e.g., email).
  - **isAuthenticated** (boolean) - Whether the user is authenticated.
  - **jwtClaims** (object) - An object containing the claims from the JWT token.

#### Response Example
```json
{
    "identity": {
        "authType": "jwt", 
        "identifier": "test@example.com",
        "isAuthenticated": true, 
        "jwtClaims": { 
            "sub": "1234567890",
            "name": "John Doe",
            "email": "test@example.com",
            "premium": true,
            "iat": 1760714314
        }
    }
}
```
```

--------------------------------

### Make JWT Surface Decision with cURL

Source: https://docs.monetizationos.com/docs/getting-started/hello-world/4-dynamic-provisioning

This snippet demonstrates how to make a surface decision using a cURL command, incorporating a JWT token for user identification. It requires an API key and a surface slug, and sends a JSON payload containing the user's JWT.

```bash
curl -X POST https://api.monetizationos.com/api/v1/surface-decisions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "surfaceSlug": "$SURFACE_SLUG",
  "identity": {
    "userJwt": "$JWT_TOKEN"
  }
}'
```

--------------------------------

### Add Dynamic Provisioning Workflow Logic

Source: https://docs.monetizationos.com/docs/getting-started/hello-world/4-dynamic-provisioning

This code defines a dynamic provisioning workflow using TypeScript. It checks for a 'premium' claim within the JWT identity and returns an array containing 'premium' if the claim is true, otherwise an empty array. This logic is used to conditionally assign plans.

```typescript
const workflow: ProvisioningWorkflow = async ({ identity }) => {
    // Assign premium if provided in JWT claims
    return identity.jwtClaims.premium ? ["premium"] : [];
};

export default workflow;
```

--------------------------------

### Make your first Surface decision

Source: https://docs.monetizationos.com/docs/getting-started/hello-world/1-surface

This endpoint allows you to retrieve decisions for a given surface and identity. It's used to check feature availability, user grants, and apply defined behaviors.

```APIDOC
## POST /api/v1/surface-decisions

### Description
Retrieves decisions for a specified surface and identity, enabling control over user interactions and content access based on monetization rules.

### Method
POST

### Endpoint
https://api.monetizationos.com/api/v1/surface-decisions

### Parameters
#### Query Parameters
None

#### Request Body
- **surfaceSlug** (string) - Required - The unique identifier (slug) of the surface for which to make a decision.
- **identity** (object) - Required - An object containing information about the user or session.
  - **anonymousIdentifier** (string) - Required - An identifier for anonymous users.

### Request Example
```json
{
  "surfaceSlug": "$SURFACE_SLUG",
  "identity": {
    "anonymousIdentifier": "test"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the request (e.g., "success").
- **eventId** (string) - A unique identifier for the event.
- **identity** (object) - Information about the identity making the request.
- **customer** (object) - Information about the customer.
- **features** (object) - Available features.
- **surfaceBehavior** (object) - Behaviors defined for the surface.
- **componentsSkipped** (boolean) - Indicates if components were skipped.
- **componentBehaviors** (object) - Behaviors defined for components.

#### Response Example
```json
{
    "status": "success",
    "eventId": "941c5b52-39ff-4dab-9031-e39ef37e061a",
    "identity": {
        "authType": "anonymous",
        "identifier": "test",
        "isAuthenticated": false,
        "jwtClaims": {}
    },
    "customer": {
        "isCustomer": false,
        "hasProducts": false,
        "customerIdentifiers": []
    },
    "features": {},
    "surfaceBehavior": {},
    "componentsSkipped": false,
    "componentBehaviors": {}
}
```
```

--------------------------------

### Successful Counter Update Response

Source: https://docs.monetizationos.com/docs/api-reference/webscale/counter-updates/updateCounters

Example of a successful response when updating usage counters. This indicates that the counter update operation was processed successfully by the API.

```JSON
{
  "status": "success"
}
```

--------------------------------

### Link Identities using WriteIdentityLinksWorkflowUtils (JavaScript)

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/WriteIdentityLinksWorkflowUtils

Demonstrates how to establish a formal relationship between two user identities using the 'link' method. It requires options specifying source, target, type, data sharing, and optional metadata.

```javascript
utils.identity.link({
  source: { identifier: 'anon_1234', userType: 'anonymous' },
  target: { identifier: 'member_1234', userType: 'authenticated' },
  type: 'conversion',
  dataSharing: 'none',
  metadata: { 'UTM Campaign': 'November launch' },
})
```

--------------------------------

### Define ReadonlyBucketWorkflowUtils Type

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/ReadonlyBucketWorkflowUtils

Defines the TypeScript type for ReadonlyBucketWorkflowUtils, ensuring that properties from WriteBucketWorkflowUtils are optional and cannot be set (marked as 'never'). It also specifies the signature for the 'get' method.

```typescript
type ReadonlyBucketWorkflowUtils = { [P in keyof WriteBucketWorkflowUtils]?: never } & {
  get: Promise<T | null>;
};
```

--------------------------------

### Valid Return Types for Dynamic Provisioning Workflows (TypeScript)

Source: https://docs.monetizationos.com/docs/api-reference/workflows/dynamic-provisioning-workflows

Illustrates valid ways to return plan slugs from a dynamic provisioning workflow. This includes returning specific plan slugs, an empty array to assign no plans, or conditionally returning slugs based on identity properties.

```typescript
// Valid return types
return ["premium", "beta-tester"];
return [];
return identity.jwtClaims.role === "admin" ? ["admin"] : ["user"];
```

--------------------------------

### ProvisioningWorkflow

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/ProvisioningWorkflow

A workflow that returns a list of plan slugs to assign to the user or session.

```APIDOC
## ProvisioningWorkflow

### Description
A workflow that returns a list of plan slugs to assign to the user or session.

### Method
N/A (Function Signature)

### Endpoint
N/A (Function Signature)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
// Example usage (assuming ProvisioningWorkflowArgs is defined elsewhere)
const workflowArgs: ProvisioningWorkflowArgs = { ... };
const result = ProvisioningWorkflow(workflowArgs);
```

### Response
#### Success Response
- **PlanSlug[]** (Promise or direct return) - An array of plan slugs.

#### Response Example
```json
["basic_plan", "premium_features"]
```
```

--------------------------------

### Accessing Environment Variables in Workflows (JavaScript)

Source: https://docs.monetizationos.com/docs/guides/environments/managing-environments

Demonstrates how to access environment variables and secrets within MonetizationOS workflows using JavaScript. It shows how to use the `env` parameter to retrieve configuration values like API endpoints and secret keys. Variables are provided as strings and might be undefined.

```javascript
export default ({ env }) => {
  console.log(env.SERVICE_URL);

  // Use variables for configuration
  const apiEndpoint = env.API_ENDPOINT;
  const secretKey = env.SECRET_API_KEY;
};
```

--------------------------------

### POST /api/v1/surface-decisions

Source: https://docs.monetizationos.com/docs/getting-started/hello-world/2-features-plans

Make a surface decision for a registered user. This endpoint allows you to retrieve feature configurations and user-specific properties based on the provided user identifier.

```APIDOC
## POST /api/v1/surface-decisions

### Description
Make a surface decision for a registered user. This endpoint allows you to retrieve feature configurations and user-specific properties based on the provided user identifier.

### Method
POST

### Endpoint
https://api.monetizationos.com/api/v1/surface-decisions

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **surfaceSlug** (string) - Required - The slug of the surface to make a decision for.
- **identity** (object) - Required - The identity of the user making the request.
  - **userIdentifier** (string) - Required - The unique identifier for the registered user.

### Request Example
```json
{
  "surfaceSlug": "$SURFACE_SLUG",
  "identity": {
    "userIdentifier": "test@example.com"
  }
}
```

### Response
#### Success Response (200)
- **identity** (object) - Details about the user's identity and authentication status.
- **features** (object) - Configuration and access status for various features.
- **surfaceBehavior** (object) - Properties derived from the surface workflow.

#### Response Example
```json
{
    "identity": {
        "authType": "provided",
        "identifier": "test@example.com",
        "isAuthenticated": true,
        "jwtClaims": {}
    },
    "features": {
        "widget": {
            "featureId": "feat_abcd1234",
            "featureSlug": "widget",
            "properties": {
                "premium": {
                    "value": true,
                    "isFallback": false
                },
                "enabled": {
                    "hasAccess": true,
                    "isFallback": false
                }
            }
        }
    },
    "surfaceBehavior": {
        "properties": {
            "userMessage": "Hello, test@example.com",
            "isAuthenticated": true,
            "widgetAccess": true,
            "premiumWidgets": false
        }
    }
}
```
```

--------------------------------

### Internal Server Error Response (JSON)

Source: https://docs.monetizationos.com/docs/api-reference/webscale/surface-decisions/performSurfaceDecision

Example JSON response for an internal server error (status code 500). It contains the status, status code, and a generic error message.

```json
{
  "status": "error",
  "statusCode": 500,
  "message": "Internal server error"
}
```

--------------------------------

### Organization Not Found Error Response (JSON)

Source: https://docs.monetizationos.com/docs/api-reference/webscale/surface-decisions/performSurfaceDecision

Example JSON response for a 'Organization not found' error (status code 404). It includes the status, status code, and the specific error message.

```json
{
  "status": "error",
  "statusCode": 404,
  "message": "Organization not found"
}
```

--------------------------------

### Update Surface Workflow Logic (TypeScript)

Source: https://docs.monetizationos.com/docs/getting-started/hello-world/2-features-plans

This TypeScript code defines a Surface workflow that utilizes feature and identity data to determine response properties. It demonstrates how to access feature flags like 'widget.enabled' and user authentication status to customize the output.

```typescript
const workflow: SurfaceWorkflow = async ({
    features, // All features and properties are available in the decision
    identity, // User identity details
}) => {
    return {
        properties: {
            userMessage: `Hello, ${identity.identifier}`,
            isAuthenticated: identity.userType === "authenticated",
            widgetAccess: features.widget.enabled.hasAccess,
            premiumWidgets: features.widget.premium,
        },
    };
};

export default workflow;
```

--------------------------------

### Define StripeApiRequest Type (TypeScript)

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/StripeApiRequest

Defines the StripeApiRequest type in TypeScript, specifying the structure for API requests. It includes an optional bodyObject, a required method (GET, POST, DELETE, PATCH, PUT), and a required path string.

```typescript
type StripeApiRequest = {
  bodyObject?: object;
  method: "GET" | "POST" | "DELETE" | "PATCH" | "PUT";
  path: string;
};
```

--------------------------------

### Invalid JSON Body Error Response (JSON)

Source: https://docs.monetizationos.com/docs/api-reference/webscale/surface-decisions/performSurfaceDecision

Example JSON response indicating an invalid JSON body error (status code 400). It includes the status, status code, and a descriptive error message.

```json
{
  "status": "error",
  "statusCode": 400,
  "message": "Invalid JSON body"
}
```

--------------------------------

### Add Basic Surface Workflow in TypeScript

Source: https://docs.monetizationos.com/docs/getting-started/hello-world/1-surface

This TypeScript code defines a simple Surface Workflow for MonetizationOS. It returns custom properties, such as 'userMessage', which will be included in the surface decision response. This workflow is designed to be used within the MonetizationOS console.

```typescript
const workflow: SurfaceWorkflow = async () => {
    return {
        // Custom user-defined properties
        properties: {
            userMessage: "Hello, World!",
        },
    };
};

export default workflow;
```

--------------------------------

### Invalid API Key Error Response (JSON)

Source: https://docs.monetizationos.com/docs/api-reference/webscale/surface-decisions/performSurfaceDecision

Example JSON response for an invalid API key error (status code 401). It provides the status, status code, and a message indicating the API key is invalid.

```json
{
  "status": "error",
  "statusCode": 401,
  "message": "Invalid API key"
}
```

--------------------------------

### Perform Surface Decision POST Request (cURL)

Source: https://docs.monetizationos.com/docs/api-reference/webscale/surface-decisions/performSurfaceDecision

Example cURL command to perform a surface decision POST request for an anonymous user. It specifies the endpoint, content type, and a JSON body containing the anonymous identifier and resource ID.

```shell
curl -X POST "https://api.monetizationos.com/api/v1/surface-decisions" \
  -H "Content-Type: application/json" \
  -d '{ \
    "identity": { \
      "anonymousIdentifier": "anon_session_789" \
    }, \
    "resource": { \
      "id": "article_xyz" \
    } \
  }'
```

--------------------------------

### System Triggers and Payloads

Source: https://docs.monetizationos.com/docs/api-reference/workflows/action-workflows

Overview of built-in system triggers provided by MonetizationOS and their corresponding payload structures.

```APIDOC
## System Triggers & Payloads

### Description
MonetizationOS provides several system-defined triggers that can initiate Action Workflows. Each trigger is associated with a specific typed payload, providing relevant context for the workflow execution. Custom triggers can also be defined with their own payload schemas.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### System Triggers & Payloads
- **Decision**: Associated with `ActionWorkflowDecisionPayload`.
- **Counters Updated**: Associated with `ActionWorkflowCounterUpdatedPayload`.
- **Plans Changed**: Associated with `ActionWorkflowPlansChangedPayload`.
- **User Added**: Does not provide a `payload`; use `identity` for user context.
```

--------------------------------

### WorkflowOfferEngineUtils Offers Properties

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/WorkflowOfferEngineUtils

Details the 'offers' property within WorkflowOfferEngineUtils, specifying the methods available for managing offerings: generate, mapToElement, and redeemOfferToken, along with their return types.

```typescript
offers: {
  generate: Promise<WorkflowOffering>;
  mapToElement: Promise<ComponentElement<Record<string, unknown>>>;
  redeemOfferToken: Promise<WorkflowRedeemAttemptResult>;
};
```

--------------------------------

### WorkflowOffering Properties (TypeScript)

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/WorkflowOffering

Details the individual properties of the WorkflowOffering type. Each property is defined with its expected data type, such as string, Record<string, any>, or a union type including null. This provides a granular view of the data structure.

```typescript
groupPresentation: Record<string, any>;
```

```typescript
id: string;
```

```typescript
offerGroupId: string;
```

```typescript
offerGroupSlug: string;
```

```typescript
presentationSchema: string | null;
```

```typescript
slots: {
  offer: WorkflowOffer | null;
  type: "single";
}[];
```

```typescript
offer: WorkflowOffer | null;
```

```typescript
type: "single";
```

--------------------------------

### Trigger Workflow with fire() Method

Source: https://docs.monetizationos.com/docs/api-reference/workflows/type-definitions/TriggerWorkflowUtils

Demonstrates the signature of the fire() method within TriggerWorkflowUtils. This method is asynchronous, accepting a trigger slug, an optional trigger payload, and an optional user identity to initiate a workflow. It returns a Promise that resolves when the workflow has been triggered.

```typescript
fire(
   triggerSlug,
   triggerPayload,
   identity?
): Promise<void>;
```
Tokens:
Raw