### Install and Configure Tapcart CLI

Source: https://dev.tapcart.com/docs/app-studio-quick-start

Installs the Tapcart CLI globally, logs into your Tapcart account, and configures your application project. Requires Node.js and npm.

```bash
npm install -g @tapcart/tapcart-cli
tapcart auth login
npm init @tapcart/tapcart-app [-- -a <application_id> -f <project_name>]
```

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

### Deploy Block to App Studio

Source: https://dev.tapcart.com/docs

Deploys the 'HelloWorld' block to App Studio, making it immediately available on the dashboard and updating all live instances. Includes confirmation output.

```bash
tapcart block push -b HelloWorld --live
```

```bash
✔ Block(s) built
✔ Block(s) pushed
```

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

### Create and Develop a New Block

Source: https://dev.tapcart.com/docs/app-studio-quick-start

Creates a new custom block named 'HelloWorld' and starts a local development server to preview the block. Uses the Tapcart CLI.

```bash
tapcart block create HelloWorld
tapcart block dev -b HelloWorld
```

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

### Add and Access Block Configuration Fields

Source: https://dev.tapcart.com/docs

Demonstrates how to add a text field to your block's `manifest.json` file and access its value within your React.js block component for rendering.

```json
{
	"id": "myFirstText",
	"label": "Text",
	"type": "text",
  "defaultValue": "Custom CMS Text In my Block"
}
```

```javascript
const { myFirstText } = blockConfig

return (
	<p>{myFirstText}</p>
)
```

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

### Manifest for Add to Cart Button Example

Source: https://dev.tapcart.com/docs/example-add-to-cart-button

This is the manifest file for the 'Add to cart' button example. It is currently empty, indicating no specific configurations or dependencies are declared for this component within the manifest.

```json
[]
```

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

### Tapcart Webhook Configuration

Source: https://dev.tapcart.com/reference/insights-stream-setup-guide

This section details how to configure your webhook receiver and the process of sending your webhook URL to Tapcart for subscription.

```APIDOC
## POST /tapcart_webhooks

### Description
This endpoint serves as the receiver for webhook events sent by Tapcart. It must be an HTTPS endpoint capable of accepting HTTP POST requests.

### Method
POST

### Endpoint
`/tapcart_webhooks` (This is an example route; your actual endpoint may vary)

### Parameters
#### Query Parameters
None

#### Request Body
This endpoint accepts a JSON payload representing a single event performed by a single user. The structure of the payload is detailed in the 'Payload Example' section below.

### Request Example
(No specific request example to send to this endpoint, as it's a receiver)

### Response
#### Success Response (200)
- **status** (string) - Indicates a successful request.

#### Response Example
```json
{
  "message": "Webhook received successfully"
}
```

### Error Handling
Tapcart expects specific HTTP status codes from your webhook receiver to indicate the outcome of processing the POST request:
- **200** – Successful Request
- **400** – Invalid Request
- **401** – Unauthorized Request
- **403** – Forbidden
- **429** – Throttling errors
- **422** – Custom errors
- **500 - 511** – Server errors

Tapcart will retry events that result in a 400 or 500 response for 5 minutes before stopping retries.

### Payload Example
Upon receiving a successful 200 POST request from the webhook, an individual payload will be received in JSON format. This event payload will include a single event performed by a single user. The webhook streams data as it's received and in its entirety.

```json
{
   "event_type":"AppOpened",
   "metadata":{
      "schema_id":"Event_AppOpened_5_0_0"
   },
   "device_properties":{
      "ip":"USER’S IP",
      "os":"iOS",
      "model":"arm64",
      "orientation":"portrait",
      "carrier":"",
      "radio":"Wifi",
      "manufacturer":"Apple",
      "lib_version":"4.1.5",
      "country":"US",
      "locale":"en",
      "wifi":true,
      "app_version":null,
      "tapcart_build":null,
      "external_build":null,
      "os_version":"15.5",
      "tapcart_commit_hash":null,
      "consumer_type":"Returning",
      "device_id":"UNIQUE DEVICE ID",
      "prev_push_enabled":false,
      "push_enabled":false
   },
   "shopify_properties":{
      "shopify_user_id":null,
      "logged_in":false
   },
   "session_properties":{
      "session_id":"UNIQUE SESSION ID",
      "source":"direct",
      "session_type":"Returning",
      "session_start_time":1692140759000,
      "notification_id":null,
      "notification_type":null,
      "utm_source":null,
      "utm_medium":null,
      "utm_campaign":null,
      "utm_content":null,
      "utm_term":null
   },
   "app_properties":{
      "app_id":"UNIQUE MERCHANT ID",
      "currency_code":"USD",
      "app_version":"1.0.0",
      "tapcart_build":"10.4.0",
      "external_build":"10.4.0",
      "os_version":"15.5",
      "tapcart_commit_hash":null,
      "environment":"debug"
   },
   "event_properties":{
      "source":null,
      "event_id":"UNIQUE EVENT ID",
      "app_open_source":"direct",
      "notification_id":null,
      "notification_type":null
   },
   "event_id":"UNIQUE EVENT ID",
   "session_id":"UNIQUE SESSION ID",
   "device_id":"UNIQUE DEVICE ID",
   "app_id":"UNIQUE MERCHANT ID",
   "timestamp":1663008666001,
   "timestamp_iso":"2023-08-15T11:51:06.000-07:00"
}
```

### Important Note
Every event received from the webhook will represent new data. The Insight Data Streaming webhook does not provide any historical data previous to when the webhook was setup.
```

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

### Deploy Block to App Studio

Source: https://dev.tapcart.com/docs/app-studio-quick-start

Deploys the 'HelloWorld' block to App Studio, making it immediately available in the dashboard and updating live instances. Uses the Tapcart CLI.

```bash
tapcart block push -b HelloWorld --live
```

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

### Fullscreen Presentation Configuration (JSON)

Source: https://dev.tapcart.com/docs/presentation

This JSON snippet illustrates how to configure a 'fullscreen' presentation type. It shows examples with both 'default' and 'flip' styles, suitable for full-screen views.

```json
{
  "type": "fullscreen",
  "style": "default"
}
```

```json
{
  "type": "fullscreen",
  "style": "flip"
}
```

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

### Example Block Code and Mock Data

Source: https://dev.tapcart.com/docs/blocks

Illustrates a basic React component for a Tapcart block (`code.jsx`) that displays a personalized greeting using variables fetched via `useVariables`. It also shows an example `mockData.json` file used for local development to provide mock customer data.

```jsx
export default function MyBlock({
    useVariables,
}) {
    const variables = useVariables();
    const customer = variables?.customer || {};

    return (
        <Text type={'h1'}>Hello {customer.firstName} from the CLI!</Text>
    );
}
```

```json
{
    "customer": {
        "id": "uuid-1234-5678-9012-345678901234",
        "firstName": "Ryan",
    }
}
```

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

### Drawer Presentation with Snap Points (JSON)

Source: https://dev.tapcart.com/docs/presentation

This JSON snippet demonstrates the configuration for a 'drawer' presentation type, utilizing 'snapPoints' for defining its behavior. Examples include 'slide-from-left' and 'slide-from-right' styles.

```json
{
  "type": "drawer",
  "style": "slide-from-left",
	"snapPoints": [".9"]
}
```

```json
{
  "type": "drawer",
  "style": "slide-from-right",
	"snapPoints": [".7"]
}
```

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

### Image Settings Configuration

Source: https://dev.tapcart.com/docs/example-collections-menu-flex-list

Defines configuration options for image display, including scaling and positioning. Supports 'fit' or 'fill' for scaling and 'left', 'center', or 'right' for positioning. No external dependencies are required for these settings.

```json
{
  "id": "imageScale",
  "label": "Image Scale",
  "type": "select",
  "defaultValue": "fill",
  "options": [
    {
      "label": "Fit",
      "value": "fit"
    },
    {
      "label": "Fill",
      "value": "fill"
    }
  ]
},
{
  "id": "imagePosition",
  "label": "Image Position",
  "type": "select",
  "defaultValue": "center",
  "options": [
    {
      "label": "Left",
      "value": "left"
    },
    {
      "label": "Center",
      "value": "center"
    },
    {
      "label": "Right",
      "value": "right"
    }
  ]
}
```

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

### GET /client/{appId}/components/{componentKey}/versions

Source: https://dev.tapcart.com/reference/get_client-appid-components-componentkey-versions

Retrieves all versions of an App Studio Component by its key. Requires write authentication.

```APIDOC
## GET /client/{appId}/components/{componentKey}/versions

### Description
Retrieves all versions of an App Studio Component by its key. Requires write auth.

### Method
GET

### Endpoint
/client/{appId}/components/{componentKey}/versions

### Parameters
#### Path Parameters
- **appId** (string) - Required - ID of the app to retrieve App Studio Components for
- **componentKey** (string) - Required - Key of the App Studio Component to retrieve versions for (ex. "ProductCard")

#### Query Parameters
- **owner** (string) - Optional - JSON string of the owner object to filter by

### Request Example
```json
{
  "example": "No request body for GET request"
}
```

### Response
#### Success Response (200)
- **versions** (array) - An array of available versions for the specified App Studio Component.

#### Response Example
```json
{
  "example": "[\"1.0.0\", \"1.1.0\", \"2.0.0\"]"
}
```

#### Error Responses
- **400** - Bad request, missing component key
- **404** - App Studio Component not found
- **500** - Internal server error
```

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

### Default Presentation Configuration (JSON)

Source: https://dev.tapcart.com/docs/presentation

This JSON snippet demonstrates the basic configuration for a 'default' presentation type with a 'default' style. It's a foundational example for setting up presentation elements.

```json
{
  "type": "default",
  "style": "default"
}
```

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

### Device Variable Usage Examples (JavaScript)

Source: https://dev.tapcart.com/docs/device

Demonstrates common use cases for device variables in JavaScript, including checking the operating system, determining screen size, handling app versions, and parsing locale information. These examples help in building adaptive and user-specific experiences.

```javascript
// Check device type
const isIOS = variables.device?.operatingSystem === 'iOS';
const isAndroid = variables.device?.operatingSystem === 'Android';

// Responsive design based on screen height
const isSmallScreen = (variables.device?.windowHeight || 0) < 700;
const containerHeight = isSmallScreen ? '300px' : '400px';

// Version-specific features
const appVersion = variables.device?.version;
const majorVersion = appVersion ? parseInt(appVersion.split('.')[0]) : 0;

// Locale-specific formatting
const userLocale = variables.device?.locale || 'en_US';
const [language, region] = userLocale.split('_');

// Device identification (changes on reinstall)
const deviceId = variables.device?.id;
```

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

### Icon Select Configuration (JSON)

Source: https://dev.tapcart.com/docs/manifest-options-for-custom-blocks

Allows users to choose an icon, specifying its type (e.g., 'internal') and URL. Includes an example of the output structure.

```json
{
  "id": "icon",
  "label": "Icon",
  "type": "icon-select",
  "defaultValue": {
    "type": "internal",
    "url": "menu-icon-heart"
  }
}

// Example Output:
{
  "icon": {
    "type": "internal",
    "url": "menu-icon-heart"
  }
}
```

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

### Configure Image Display Options

Source: https://dev.tapcart.com/docs/example-collections-menu-flex-list

Specifies how images are displayed, including aspect ratio, scaling behavior (fit or fill), and horizontal positioning. Default settings are '1/1' ratio, 'fill' scale, and 'center' position.

```json
{
  "id": "imageRatio",
  "label": "Image Ratio",
  "type": "select",
  "defaultValue": "1/1",
  "options": [
    {
      "label": "1:1",
      "value": "1/1"
    },
    {
      "label": "2:3",
      "value": "2/3"
    },
    {
      "label": "4:5",
      "value": "4/5"
    },
    {
      "label": "2:1",
      "value": "2/1"
    },
    {
      "label": "4:1",
      "value": "4/1"
    },
    {
      "label": "5:1",
      "value": "5/1"
    }
  ]
},
{
  "id": "imageScale",
  "label": "Image Scale",
  "type": "select",
  "defaultValue": "fill",
  "options": [
    {
      "label": "Fit",
      "value": "fit"
    },
    {
      "label": "Fill",
      "value": "fill"
    }
  ]
},
{
  "id": "imagePosition",
  "label": "Image Position",
  "type": "select",
  "defaultValue": "center",
  "options": [
    {
      "label": "Left",
      "value": "left"
    },
    {
      "label": "Center",
      "value": "center"
    },
    {
      "label": "Right",
      "value": "right"
    }
  ]
}
```

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

### React Main Collections Menu Example Component

Source: https://dev.tapcart.com/docs/example-collections-menu-flex-list

The main component for the collections menu example, managing the state for drawer visibility, selected collection, and interaction with Tapcart's services. It orchestrates the display of the subcollection drawer.

```jsx
export default function CollectionsMenuExample({ blockConfig, useTapcart, __tapcartDashboard }) {
  const Tapcart = useTapcart();
  const [isOpen, setIsOpen] = React.useState(false);
  const [canOpen, setCanOpen] = React.useState(true);
  const [selectedCollection, setSelectedCollection] = React.useState(null);

  const { collections, collectionListSettings, subcollectionSettings } = blockConfig;


```

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

### Configure Title Typography and Appearance

Source: https://dev.tapcart.com/docs/example-collections-menu-flex-list

Manages the visual styling of titles, including font selection, size, color, and case. It also allows for customization of the title's background color and border-radius.

```json
{
  "id": "font",
  "label": "Font",
  "type": "font-select",
  "defaultValue": {
    "family": "unset",
    "weight": "unset"
  }
},
{
  "id": "size",
  "label": "Size",
  "type": "range",
  "defaultValue": 16,
  "min": 8,
  "max": 36,
  "unit": "px",
  "step": 1
},
{
  "id": "color",
  "label": "Color",
  "type": "color-select",
  "defaultValue": {
    "type": "brand-kit",
    "value": "buttonColors-primaryText"
  }
},
{
  "id": "uppercase",
  "label": "Uppercase",
  "type": "toggle",
  "defaultValue": false
},
{
  "id": "backgroundColor",
  "label": "Background Color",
  "type": "color-select",
  "defaultValue": {
    "type": null,
    "value": null
  }
},
{
  "id": "borderRadius",
  "label": "Corners",
  "type": "range",
  "defaultValue": 4,
  "min": 0,
  "max": 50,
  "unit": "px"
}
```

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

### Configure Padding Settings

Source: https://dev.tapcart.com/docs/example-collections-menu-flex-list

Sets the padding values for UI elements, allowing for individual adjustments to top, bottom, left, and right margins. Defaults are set to 8 pixels for all sides.

```json
{
  "id": "padding",
  "type": "padding",
  "label": "",
  "defaultValue": {
    "top": 8,
    "bottom": 8,
    "left": 8,
    "right": 8
  }
}
```

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

### GET /client/{appId}/dependencies

Source: https://dev.tapcart.com/reference/get_client-appid-dependencies

Retrieves the dependencies of an app identified by the appId.

```APIDOC
## GET /client/{appId}/dependencies

### Description
Retrieves the dependencies of an app identified by the appId.

### Method
GET

### Endpoint
/client/{appId}/dependencies

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the app.

### Response
#### Success Response (200)
- **dependencies** (array[string]) - A list of dependency names.

#### Response Example
```json
{
  "dependencies": [
    "dependency1",
    "dependency2"
  ]
}
```

#### Error Response (404)
- **description**: No dependencies found for the given appId.

#### Error Response (500)
- **description**: Server error.
```

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

### Tapcart Webhook Event Payload Example

Source: https://dev.tapcart.com/reference/insights-stream-setup-guide

An example of a JSON payload received from Tapcart's Insight Data Streaming webhook. This payload represents an 'AppOpened' event and includes detailed properties related to the device, session, application, and event specifics.

```json
{
   "event_type":"AppOpened",
   "metadata":{
      "schema_id":"Event_AppOpened_5_0_0"
   },
   "device_properties":{
      "ip":"USER’S IP",
      "os":"iOS",
      "model":"arm64",
      "orientation":"portrait",
      "carrier":"",
      "radio":"Wifi",
      "manufacturer":"Apple",
      "lib_version":"4.1.5",
      "country":"US",
      "locale":"en",
      "wifi":true,
      "app_version":null,
      "tapcart_build":null,
      "external_build":null,
      "os_version":"15.5",
      "tapcart_commit_hash":null,
      "consumer_type":"Returning",
      "device_id":"UNIQUE DEVICE ID",
      "prev_push_enabled":false,
      "push_enabled":false
   },
   "shopify_properties":{
      "shopify_user_id":null,
      "logged_in":false
   },
   "session_properties":{
      "session_id":"UNIQUE SESSION ID",
      "source":"direct",
      "session_type":"Returning",
      "session_start_time":1692140759000,
      "notification_id":null,
      "notification_type":null,
      "utm_source":null,
      "utm_medium":null,
      "utm_campaign":null,
      "utm_content":null,
      "utm_term":null
   },
   "app_properties":{
      "app_id":"UNIQUE MERCHANT ID",
      "currency_code":"USD",
      "app_version":"1.0.0",
      "tapcart_build":"10.4.0",
      "external_build":"10.4.0",
      "os_version":"15.5",
      "tapcart_commit_hash":null,
      "environment":"debug"
   },
   "event_properties":{
      "source":null,
      "event_id":"UNIQUE EVENT ID",
      "app_open_source":"direct",
      "notification_id":null,
      "notification_type":null
   },
   "event_id":"UNIQUE EVENT ID",
   "session_id":"UNIQUE SESSION ID",
   "device_id":"UNIQUE DEVICE ID",
   "app_id":"UNIQUE MERCHANT ID",
   "timestamp":1663008666001,
   "timestamp_iso":"2023-08-15T11:51:06.000-07:00"
}
```

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

### Define Webhook Endpoint in Python

Source: https://dev.tapcart.com/reference/insights-stream-setup-guide

This Python snippet demonstrates how to define a route for receiving webhook POST requests using Flask. It specifies the endpoint path and the allowed HTTP method.

```python
@app.route('/tapcart_webhooks', methods=['POST'])
```

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

### Mock Data for Development (JSON)

Source: https://dev.tapcart.com/docs/example-open-screen-navigate

This JSON object provides mock data for the 'customer' object, including a 'firstName' property. This is optional and used for development purposes when experimenting with `useVariables` to simulate data without needing a live backend.

```json
{
  "customer": {
    "firstName": "Taylor"
  }
}
```

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

### Tapcart Webhook Event Payload Example

Source: https://dev.tapcart.com/reference

This JSON object represents a typical event payload received by a Tapcart webhook. It includes details about the event type, device properties, session information, Shopify-specific data, and application properties.

```json
{
  "event_type":"AppOpened",
  "metadata":{
     "schema_id":"Event_AppOpened_5_0_0"
  },
  "device_properties":{
     "ip":"USER’S IP",
     "os":"iOS",
     "model":"arm64",
     "orientation":"portrait",
     "carrier":"",
     "radio":"Wifi",
     "manufacturer":"Apple",
     "lib_version":"4.1.5",
     "country":"US",
     "locale":"en",
     "wifi":true,
     "app_version":null,
     "tapcart_build":null,
     "external_build":null,
     "os_version":"15.5",
     "tapcart_commit_hash":null,
     "consumer_type":"Returning",
     "device_id":"UNIQUE DEVICE ID",
     "prev_push_enabled":false,
     "push_enabled":false
  },
  "shopify_properties":{
     "shopify_user_id":null,
     "logged_in":false
  },
  "session_properties":{
     "session_id":"UNIQUE SESSION ID",
     "source":"direct",
     "session_type":"Returning",
     "session_start_time":1692140759000,
     "notification_id":null,
     "notification_type":null,
     "utm_source":null,
     "utm_medium":null,
     "utm_campaign":null,
     "utm_content":null,
     "utm_term":null
  },
  "app_properties":{
     "app_id":"UNIQUE MERCHANT ID",
     "currency_code":"USD",
     "app_version":"1.0.0",
     "tapcart_build":"10.4.0",
     "external_build":"10.4.0",
     "os_version":"15.5",
     "tapcart_commit_hash":null,
     "environment":"debug"
  },
  "event_properties":{
     "source":null,
     "event_id":"UNIQUE EVENT ID",
     "app_open_source":"direct",
     "notification_id":null,
     "notification_type":null
  },
  "event_id":UNIQUE EVENT ID",
  "session_id":"UNIQUE SESSION ID",
  "device_id":"UNIQUE DEVICE ID",
  "app_id":"UNIQUE MERCHANT ID",
  "timestamp":1663008666001,
  "timestamp_iso":"2023-08-15T11:51:06.000-07:00"
}

```

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

### App Installed Event

Source: https://dev.tapcart.com/reference/app-installed

The App Installed event fires the first time a user installs and opens the mobile app. It includes properties like event_id and source.

```APIDOC
## App Installed Event

### Description
This event fires when a user installs and opens the mobile app for the first time. It indicates a successful installation and is tracked alongside App Opened and Session Started events.

### Method
Not Applicable (This is an event, not an API endpoint)

### Endpoint
Not Applicable

### Parameters
#### Event Properties
- **event_id** (String) - Required - The unique identifier of the session associated with the event. This property also exists on the Event object level.
- **source** (String) - Required - Indicates if the install source was direct or via a specific deeplink.

### Request Example
```json
{
    "event_properties": {
        "event_id": "4ge4db71-42e9-41e8-8bb7-bd098e9e99d9",
        "source":  "direct"
    }
}
```

### Response
#### Success Response (200)
Not Applicable (This is an event payload, not a typical API response)

#### Response Example
Not Applicable
```

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

### App Installed Event Properties (JSON)

Source: https://dev.tapcart.com/reference/app-installed

This JSON snippet illustrates the event properties specific to the App Installed event. It includes a unique event_id for the session and a source property indicating how the app was installed (e.g., direct or via deeplink).

```json
{
    "event_properties": {
        “event_id”: "4ge4db71-42e9-41e8-8bb7-bd098e9e99d9",
        "source":  "direct"
    }
}
```

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

### Session Started Event Properties (JSON)

Source: https://dev.tapcart.com/reference/session-started

This JSON structure outlines the properties associated with a 'Session Started' event. It includes details such as the event source, unique session identifiers, session type, and start time. These properties are crucial for tracking user engagement and session behavior within the application.

```json
{
  "event_properties":{
      "source":"direct",
      "event_id":"UNIQUE SESSION ID",
      "session_id":"UNIQUE SESSION ID",
      "session_source":"direct",
      "session_type":"Returning",
      "session_start_time":1692140759000,
      "notification_id":null,
      "notification_type":null,
      "segment_id":null
   }
}
```

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

### Mock Data Configuration (JSON)

Source: https://dev.tapcart.com/docs/example-collection-bar

This JSON file provides mock data for the project, specifically for device information like locale. It is noted as optional and not required if the project does not use `useVariables` or mock `useCollection` results.

```json
{
  "device": {
    "locale": "en-US"
  }
}

```

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

### Mock Data for Local Development

Source: https://dev.tapcart.com/docs/example-add-to-cart-personalization-mock-data

This JSON file provides mock data for customer information, specifically the first name. It is intended to be placed alongside the `code.jsx` file for local development and testing purposes, particularly for the `useVariables()` hook.

```json
{
  "customer": {
    "id": "<UUID>",
    "firstName": "Taylor"
  }
}

```

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

### POST /client/components

Source: https://dev.tapcart.com/reference/post_client-components

Creates a new App Studio Component or updates an existing one if `forceUpdate` is true. Requires write authorization.

```APIDOC
## POST /client/components

### Description
Creates a new App Studio Component or updates an existing one if `forceUpdate` is true. Requires write auth.

### Method
POST

### Endpoint
/client/components

### Parameters
#### Query Parameters
- **forceUpdate** (boolean) - Optional - If true, forces an update on an existing Component.

#### Request Body
- **owner** (object) - Required - Owner details.
  - **type** (string) - Required - Owner type (e.g., 'app').
  - **id** (string) - Required - Owner ID (required if owner type is 'app').
- **label** (string) - Required - The label of the Component.
- **key** (string) - Required - The key of the Component.
- **code** (string) - Optional - The source code for the Component.
- **transpiledCode** (string) - Optional - The transpiled code for the Component.
- **manifestOptionsList** (array) - Optional - List of manifest options.
- **updateDescription** (string) - Optional - Description for the update.
- **tags** (array) - Optional - Tags associated with the Component.
- **status** (string) - Optional - Status of the Component.

### Request Example
```json
{
  "owner": {
    "type": "app",
    "id": "your-app-id"
  },
  "label": "My Component",
  "key": "my-component-key",
  "code": "<div>Hello World</div>",
  "forceUpdate": false
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating success.

#### Response Example
```json
{
  "message": "App Studio Component created successfully."
}
```

#### Error Responses
- **400 Bad Request**: Missing required fields or invalid data format.
- **401 Unauthorized**: Authentication token is missing or invalid.
- **404 Not Found**: Component not found when `forceUpdate` is true.
- **500 Internal Server Error**: An unexpected error occurred on the server.
```

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

### Start Local Development Server for Blocks

Source: https://dev.tapcart.com/docs/blocks

Initiate a local development server to preview and test your custom blocks in real-time. The server typically runs at `http://localhost:4995` and supports hot reloading for block code, but not for manifest files.

```bash
yarn tapcart block dev
```

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

### Example Usage of Supported Data Types with Storage Variables

Source: https://dev.tapcart.com/docs/storage-1

Demonstrates how to access various JSON-serializable data types stored via storage variables. It includes examples for strings, numbers, booleans, objects, arrays, and null values. Unsupported types like functions or undefined will be converted during serialization.

```javascript
// Supported data types
const examples = {
  string: variables.storage?.name,
  number: variables.storage?.age,
  boolean: variables.storage?.isActive,
  object: variables.storage?.profile,
  array: variables.storage?.tags,
  null: variables.storage?.optionalField
};

// Unsupported: functions, undefined, symbols, etc.
// These will be converted during serialization
```

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

### Loyalty Tiers Structure

Source: https://dev.tapcart.com/docs/loyalty

This section outlines the structure of loyalty tiers, including their properties, types, and examples.

```APIDOC
## Loyalty Tiers

### Description
Provides details about the structure and properties of loyalty tiers.

### Method
GET

### Endpoint
/websites/dev_tapcart/loyalty/tiers

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **loyalty.tiers** (Array) - An array of loyalty tier objects.
  - **loyalty.tiers[].id** (String) - The unique identifier for the tier.
  - **loyalty.tiers[].name** (String) - The name of the tier (e.g., "Bronze").
  - **loyalty.tiers[].level** (Number) - The numerical level of the tier.
  - **loyalty.tiers[].isActive** (Boolean) - Indicates if the tier is currently active.
  - **loyalty.tiers[].benefits** (Array) - A list of benefits associated with the tier.

#### Response Example
```json
{
  "loyalty": {
    "tiers": [
      {
        "id": "12345",
        "name": "Bronze",
        "level": 1,
        "isActive": false,
        "benefits": [
          "Free Shipping",
          "Priority Support"
        ]
      }
    ]
  }
}
```
```

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

### Metafield Structure Example in JavaScript

Source: https://dev.tapcart.com/docs/customer

This code snippet illustrates the structure of a metafield object in JavaScript. Metafields are used to store custom data associated with a customer, such as loyalty tier. Before using metafields, they must be enabled and configured within the Tapcart app settings. This example shows a typical metafield with namespace, key, and value properties.

```javascript
// Metafield structure
const metafield = {
  namespace: 'loyalty',
  key: 'tier',
  value: 'gold'
};
```

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

### Configure Item Styling Options

Source: https://dev.tapcart.com/docs/example-collections-menu-flex-list

Defines styling properties for individual items, including background color, corner radius, and drop shadow. It utilizes a 'brand-kit' for default color selection and allows for pixel-based adjustments to corners.

```json
{
  "id": "itemBackgroundColor",
  "label": "Item Background Color",
  "type": "color-select",
  "defaultValue": {
    "type": "brand-kit",
    "value": "coreColors-pageColor"
  }
},
{
  "id": "cornerRadius",
  "label": "Item Corners",
  "type": "range",
  "defaultValue": 12,
  "min": 0,
  "max": 9999,
  "unit": "px",
  "step": 1
},
{
  "id": "showDropshadow",
  "label": "Show Drop Shadow",
  "type": "toggle",
  "defaultValue": false
}
```

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

### GET /websites/dev_tapcart/apps/{appId}/layouts

Source: https://dev.tapcart.com/reference/get_client-appid-layouts

Retrieves a list of layouts for a specified application ID. This endpoint requires read authentication.

```APIDOC
## GET /websites/dev_tapcart/apps/{appId}/layouts

### Description
Returns a list of layouts for the specified appId. Requires read auth.

### Method
GET

### Endpoint
/websites/dev_tapcart/apps/{appId}/layouts

### Parameters
#### Path Parameters
- **appId** (string) - Required - The unique identifier of the application.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **layouts** (array) - A list of layout objects associated with the app.
  - **layoutId** (string) - The unique identifier of the layout.
  - **name** (string) - The name of the layout.
  - **type** (string) - The type of the layout (e.g., 'mobile', 'desktop').

#### Response Example
```json
{
  "layouts": [
    {
      "layoutId": "layout_123",
      "name": "Homepage Layout",
      "type": "mobile"
    },
    {
      "layoutId": "layout_456",
      "name": "Product Detail Layout",
      "type": "desktop"
    }
  ]
}
```
```

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

### GET /client/{appId}/blockTemplates/{blockTemplateId}

Source: https://dev.tapcart.com/reference/get_client-appid-blocktemplates-blocktemplateid

Retrieves a BlockTemplate along with the specified version based on `versionIndex`. Requires read authentication.

```APIDOC
## GET /client/{appId}/blockTemplates/{blockTemplateId}

### Description
Retrieves a BlockTemplate along with the specified version based on `versionIndex`. Requires read auth.

### Method
GET

### Endpoint
/client/{appId}/blockTemplates/{blockTemplateId}

### Parameters
#### Path Parameters
- **blockTemplateId** (string) - Required - The ID of the BlockTemplate to retrieve.
- **appId** (string) - Required - The ID of the app.

#### Query Parameters
- **versionIndex** (number) - Optional - The version index to retrieve. If not provided, the current versionIndex is used.

### Request Example
```json
{
  "example": "No request body for GET request"
}
```

### Response
#### Success Response (200)
- **blockTemplate** (object) - The retrieved BlockTemplate object.

#### Response Example
```json
{
  "blockTemplate": {}
}
```

#### Error Responses
- **400**: Invalid versionIndex or label not found.
- **401**: Unauthorized access.
- **404**: BlockTemplate version not found.
- **500**: Internal server error.
```

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

### Example JSON for Navigating to Screens

Source: https://dev.tapcart.com/docs/action

This JSON object demonstrates how to configure the 'destination' and 'data' fields to navigate users to a specific screen within the Tapcart app. It specifies the 'type' as 'screen' and provides an 'id' for the target screen.

```json
{
  "type": "open/screen",
  "data": {
    "destination": {
      "type": "screen",
      "id": "9M5lEgg5up"
    },
    "presentation": {
      "transition": "default",
      "style": "default"
    }
  }
}
```

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

### Title Settings Configuration

Source: https://dev.tapcart.com/docs/example-collections-menu-flex-list

Configures the visual appearance of titles, including typography, background, border, and spacing. It allows customization of font family, size, color, uppercase, background color, corner radius, border color and sides, text alignment, padding, and margin. Default values are provided for all settings.

```json
{
  "id": "titleSettings",
  "label": "Title Settings",
  "type": "section",
  "defaultValue": true,
  "manifestOptions": [
    {
      "type": "header",
      "label": "Typography"
    },
    {
      "id": "font",
      "label": "Font",
      "type": "font-select",
      "defaultValue": {
        "family": "unset",
        "weight": "unset"
      }
    },
    {
      "id": "size",
      "label": "Size",
      "type": "range",
      "defaultValue": 16,
      "min": 8,
      "max": 36,
      "unit": "px",
      "step": 1
    },
    {
      "id": "color",
      "label": "Color",
      "type": "color-select",
      "defaultValue": {
        "type": "brand-kit",
        "value": "buttonColors-primaryText"
      }
    },
    {
      "id": "uppercase",
      "label": "Uppercase",
      "type": "toggle",
      "defaultValue": false
    },
    {
      "type": "divider"
    },
    {
      "type": "header",
      "label": "Background"
    },
    {
      "id": "backgroundColor",
      "label": "Background Color",
      "type": "color-select",
      "defaultValue": {
        "type": null,
        "value": null
      }
    },
    {
      "id": "borderRadius",
      "label": "Corners",
      "type": "range",
      "defaultValue": 4,
      "min": 0,
      "max": 50,
      "unit": "px"
    },
    {
      "type": "divider"
    },
    {
      "type": "header",
      "label": "Border"
    },
    {
      "id": "borderColor",
      "label": "Border Color",
      "type": "color-select",
      "defaultValue": {
        "type": "brand-kit",
        "value": "buttonColors-primaryOutlineColor"
      }
    },
    {
      "id": "borderSides",
      "label": "Sides",
      "type": "border-sides",
      "defaultValue": [
        "none"
      ]
    },
    {
      "type": "divider"
    },
    {
      "type": "header",
      "label": "Alignment and Padding"
    },
    {
      "id": "textAlignment",
      "label": "Alignment",
      "type": "text_alignment",
      "defaultValue": "center"
    },
    {
      "id": "padding",
      "label": "Padding",
      "type": "padding",
      "defaultValue": {
        "top": 8,
        "bottom": 8,
        "left": 16,
        "right": 16
      }
    },
    {
      "type": "header",
      "label": "Margin"
    },
    {
      "id": "margin",
      "label": "Margin",
      "type": "padding",
      "defaultValue": {
        "top": 0,
        "bottom": 0,
        "left": 0,
        "right": 0
      }
    }
  ]
}
```

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

### GET loyalty/customer

Source: https://dev.tapcart.com/docs/loyaltycustomer

Retrieves the logged-in user's loyalty data and available activities.

```APIDOC
## GET loyalty/customer

### Description
Retrieves the logged-in user's loyalty data as well as the users available activities.

### Method
GET

### Endpoint
/loyalty/customer

### Parameters
#### Query Parameters
- **appId** (string) - Required - The unique identifier for the store. This value is accessible at the block level via `tapcartData?.appId`

### Request Example
```javascript
Tapcart.action("loyalty/customer", {
  appId: "AbC123XyZ9",
});

// Alternatively
Tapcart.actions?.getLoyaltyCustomer({
  appId: tapcartData?.appId
})
```

### Response
#### Success Response (200)
No response data is returned directly. Instead, the result is stored in the app variables under `Tapcart.loyalty.customer` and `Tapcart.loyalty.activities`.

> ⚠️ Important Notes
> * This data becomes available upon customer login `customer/login` and can be accessed under app variables at `Tapcart.loyalty.customer`.
```

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

### Manifest Configuration for Goal Amount

Source: https://dev.tapcart.com/docs/example-goal-progress-mock-data

A JSON manifest file defining the configuration options for the goal progress bar component. It specifies a 'range' type input for 'goalAmount', allowing users to set the target value with a default of 50, a minimum of 0, and a maximum of 500.

```json
[
  {
    "id": "goalAmount",
    "label": "Goal amount",
    "type": "range",
    "defaultValue": 50,
    "min": 0,
    "max": 500,
    "unit": "",
    "step": 1
  }
]
```

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

### GET /websites/dev_tapcart/layouts

Source: https://dev.tapcart.com/reference/get_client-appid-layouts

Retrieves a list of layouts for the specified website. This endpoint allows fetching layout configurations, including details about blocks, read-only status, and template usage.

```APIDOC
## GET /websites/dev_tapcart/layouts

### Description
Retrieves a list of layouts for the specified website. This endpoint allows fetching layout configurations, including details about blocks, read-only status, and template usage.

### Method
GET

### Endpoint
/websites/dev_tapcart/layouts

### Parameters
#### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response.

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **data** (array) - An array of layout objects.
  - **id** (string) - The unique identifier for the layout.
  - **name** (string) - The name of the layout.
  - **blocks** (object) - Configuration of the blocks within the layout.
    - **type** (string) - The type of the block.
    - **description** (string) - Description of the block.
    - **readOnly** (boolean) - Indicates if the block is readOnly.
    - **blockTemplateId** (string) - The ID of the block template.
    - **useBlockTemplate** (boolean) - Indicates if the block uses a template.
    - **createdAt** (string) - The creation date of the block.
    - **updatedAt** (string) - The last update date of the block.
  - **readOnly** (boolean) - Indicates if the layout is readOnly.
  - **layoutTemplateId** (string) - The ID of the layout template.
  - **useLayoutTemplate** (boolean) - Indicates if the layout uses a template.
  - **createdAt** (string) - The creation date of the layout.
  - **updatedAt** (string) - The last update date of the layout.

#### Response Example
```json
{
  "data": [
    {
      "id": "layout-123",
      "name": "Homepage Layout",
      "blocks": {
        "header": {
          "type": "object",
          "description": "The configuration of the header block",
          "readOnly": false,
          "blockTemplateId": "template-abc",
          "useBlockTemplate": true,
          "createdAt": "2023-10-27T10:00:00Z",
          "updatedAt": "2023-10-27T10:00:00Z"
        }
      },
      "readOnly": false,
      "layoutTemplateId": "template-xyz",
      "useLayoutTemplate": true,
      "createdAt": "2023-10-27T09:00:00Z",
      "updatedAt": "2023-10-27T09:30:00Z"
    }
  ]
}
```

#### Error Response (404)
- **description**: Layouts not found

#### Error Response (500)
- **description**: Server error
```

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

### GET /client/{appId}/layouts

Source: https://dev.tapcart.com/reference/get_client-appid-layouts

Retrieve layouts for a specific app. This endpoint returns a list of layouts associated with the provided appId. Authentication with read permissions is required.

```APIDOC
## GET /client/{appId}/layouts

### Description
Retrieve layouts for a specific app. Returns a list of layouts for the specified appId. Requires read auth.

### Method
GET

### Endpoint
/client/{appId}/layouts

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the app

#### Query Parameters
- **type** (string) - Optional - The type of the layout
- **limit** (integer) - Optional - The number of layouts to return
- **sort** (string) - Optional - The sort order of the layouts (enum: asc, desc)
- **readonly** (boolean) - Optional - Whether to include readonly layouts

### Request Example
```json
{
  "example": "No request body for GET request"
}
```

### Response
#### Success Response (200)
- **_id** (string) - The ID of the layout
- **appId** (string) - The ID of the app
- **label** (string) - The label of the layout
- **type** (string) - The type of the layout
- **blocks** (array) - A list of blocks within the layout
  - **_id** (string) - The ID of the block
  - **appId** (string) - The ID of the app
  - **label** (string) - The label of the block
  - **code** (string) - The code of the block
  - **manifestOptionsList** (array) - A list of manifest options for the block
    - **id** (string) - The ID of the manifest option
    - **label** (string) - The label of the manifest option
    - **type** (string) - The type of the manifest option
    - **defaultValue** (object) - The default value of the manifest option
  - **manifestConfig** (object) - The manifest configuration for the block

#### Response Example
```json
{
  "example": "[
  {
    "_id": "layout123",
    "appId": "app456",
    "label": "Homepage Layout",
    "type": "page",
    "blocks": [
      {
        "_id": "block789",
        "appId": "app456",
        "label": "Header Block",
        "code": "<header>...</header>",
        "manifestOptionsList": [
          {
            "id": "option1",
            "label": "Header Title",
            "type": "text",
            "defaultValue": "Welcome!"
          }
        ],
        "manifestConfig": {
          "backgroundColor": "#FFFFFF"
        }
      }
    ]
  }
]"
}
```
```