### MultiQueryParamTokenAuthentication Example

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/interfaces/MultiQueryParamTokenAuthentication.md

Example of how to set up MultiQueryParamToken authentication in a pack.

```APIDOC
## MultiQueryParamTokenAuthentication

Authenticate using multiple tokens, each passed as a different URL parameter, e.g.
`https://example.com/api?param1=token1&param2=token2`.

The parameter names are defined in the `params` array property.

### Example

```ts
pack.setUserAuthentication({
  type: sdk.AuthenticationType.MultiQueryParamToken,
  params: [
    { name: "key", description: "The key." },
    { name: "secret", description: "The secret." },
  ],
});
```

### Properties

#### params

- **params** (object[]) - Required - Names and descriptions of the query parameters used for authentication.
  - **name** (string) - Required - The name of the query parameter, e.g. "foo" if a token is passed as "foo=bar".
  - **description** (string) - Required - A description shown to the user indicating what value they should provide for this parameter.

#### type

- **type** (MultiQueryParamToken) - Required - Identifies this as MultiQueryParamToken authentication.

#### endpointDomain?

- **endpointDomain** (string) - Optional - When requiresEndpointUrl is set to true, this should be the root domain that all endpoints share.

#### getConnectionName?

- **getConnectionName** (MetadataFormula) - Optional - A function that is called when a user sets up a new account, that returns a name for the account to label that account in the UI.

#### instructionsUrl?

- **instructionsUrl** (string) - Optional - A link to a help article or other page with more instructions about how to set up an account for this pack.

#### networkDomain?

- **networkDomain** (string | string[]) - Optional - Which domain(s) should get auth credentials, when a pack is configured with multiple domains.

#### postSetup?

- **postSetup** (SetEndpoint[]) - Optional - One or more setup steps to run after the user has set up the account, before completing installation of the pack.

#### requiresEndpointUrl?

- **requiresEndpointUrl** (boolean) - Optional - If true, indicates this pack has a specific endpoint domain for each account, that is used as the basis of HTTP requests.
```

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

### Initialize npm Project and Install Packs SDK

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/development/cli.md

Initialize your project with npm and install the Packs SDK locally. This is the recommended approach for managing dependencies and avoiding version conflicts.

```sh
# Initialize npm and follow prompts.
npm init

# Install the Packs SDK locally in your project
npm install --save @codahq/packs-sdk
```

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

### Install the Coda Packs SDK

Source: https://github.com/coda/packs-sdk/blob/main/docs/tutorials/get-started/cli.md

Install the Pack SDK as a project dependency. This includes the `packs` CLI and necessary libraries for building Packs.

```sh
npm install --save @codahq/packs-sdk
```

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

### Install a Library with NPM

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/development/libraries.md

Use the `npm install` command to add libraries to your Pack. This command is executed in your terminal.

```sh
npm install lodash
```

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

### Install Packs SDK Globally

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/development/cli.md

Install the Packs SDK globally to access the CLI from any directory. This is an alternative to a single-project install.

```sh
npm install --global @codahq/packs-sdk
```

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

### QueryParamTokenAuthentication Example

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/interfaces/QueryParamTokenAuthentication.md

This example demonstrates how to configure QueryParamToken authentication in your Coda pack.

```APIDOC
## QueryParamTokenAuthentication

Authenticate using a token that is passed as a URL parameter with each request, e.g. `https://example.com/api?paramName=token`.

The parameter name is defined in the `paramName` property.

### Properties

#### paramName

- **paramName** (string) - Required - The name of the query parameter that will include the token, e.g. "foo" if a token is passed as "foo=bar".

#### type

- **type** (AuthenticationType.QueryParamToken) - Required - Identifies this as QueryParamToken authentication.

### Example Usage

```ts
pack.setUserAuthentication({
  type: sdk.AuthenticationType.QueryParamToken,
  paramName: "key",
});
```
```

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

### MultiHeaderTokenAuthentication Example

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/interfaces/MultiHeaderTokenAuthentication.md

This example demonstrates how to set up multi-header token authentication using the Coda SDK. It shows how to define multiple headers, including their names, descriptions, and optional token prefixes.

```APIDOC
## MultiHeaderTokenAuthentication Configuration

### Description
Configure authentication for your pack using multiple HTTP headers. This method allows you to specify several headers, each with a name, a user-facing description, and an optional token prefix.

### Usage
```ts
pack.setUserAuthentication({
  type: sdk.AuthenticationType.MultiHeaderToken,
  headers: [
    {name: 'Header1', description: 'Enter the value for Header1',  tokenPrefix: 'prefix1'},
    {name: 'Header2', description: 'Enter value for Header2'},
  ],
});
```

### Properties

- **type** (AuthenticationType.MultiHeaderToken) - Required - Identifies this as MultiHeaderToken authentication.
- **headers** (object[]) - Required - An array of objects, where each object defines a header for authentication.
  - **name** (string) - Required - The name of the HTTP header.
  - **description** (string) - Required - A description shown to the user for providing the header value.
  - **tokenPrefix** (string) - Optional - A prefix for the HTTP header value, e.g., 'Bearer '. The header will be formatted as `<headerName>: <tokenPrefix> <token>`.
- **endpointDomain** (string) - Optional - The root domain for all endpoints when `requiresEndpointUrl` is true.
- **getConnectionName** (MetadataFormula) - Optional - A function to generate a user-friendly name for the account.
- **instructionsUrl** (string) - Optional - A URL to a help article for setting up the account.
- **networkDomain** (string | string[]) - Optional - Specifies which domain(s) should receive authentication credentials.
- **postSetup** (SetEndpoint[]) - Optional - Setup steps to run after the user has set up the account.
- **requiresEndpointUrl** (boolean) - Optional - If true, prompts the user to provide their specific endpoint domain.
```

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

### OAuth2ClientCredentialsAuthentication Example

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/interfaces/OAuth2ClientCredentialsAuthentication.md

Example of how to configure OAuth2ClientCredentials authentication in a Coda pack.

```APIDOC
## OAuth2ClientCredentialsAuthentication Configuration

### Description

This example demonstrates how to set up OAuth2 Client Credentials authentication for a Coda pack. It specifies the authentication type and the token exchange URL.

### Usage

```ts
pack.setUserAuthentication({
  type: sdk.AuthenticationType.OAuth2ClientCredentials,
  // This URL comes from the API's developer documentation.
  tokenUrl: "https://api.example.com/token",
});
```

### Properties

This interface extends `BaseOAuthAuthentication` and includes the following properties:

*   **credentialsLocation?** (`optional` `TokenExchangeCredentialsLocation`): Specifies where to pass client credentials in the token exchange request. Defaults to `TokenExchangeCredentialsLocation#Automatic`.
*   **endpointDomain?** (`optional` `string`): The root domain for endpoints when `requiresEndpointUrl` is true.
*   **getConnectionName?** (`optional` `MetadataFormula`): A function to return a name for the account in the UI.
*   **instructionsUrl?** (`optional` `string`): A link to setup instructions.
*   **nestedResponseKey?** (`optional` `string`): Key for nested access tokens in the authentication response.
*   **networkDomain?** (`optional` `string` | `string[]`): Domain(s) that should receive auth credentials.
*   **postSetup?** (`optional` `SetEndpoint[]`): Setup steps to run after account setup.
*   **requiresEndpointUrl?** (`optional` `boolean`): If true, prompts the user for their specific endpoint domain.
*   **scopeDelimiter?** (`optional` `
```

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

### Define Formula with Examples

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/blocks/formulas.md

Add entries to the `examples` array to demonstrate how the formula should be used. Each example is a structured object containing a set of parameters and the corresponding result, with types matching those defined in your formula.

```typescript
pack.addFormula({
  name: "ToUSD",
  description: "Convert from a different currency to US dollars.",
  parameters: [
    sdk.makeParameter({
      type: sdk.ParameterType.Number,
      name: "amount",
      description: "The amount to convert."
    }),
    sdk.makeParameter({
      type: sdk.ParameterType.String,
      name: "from",
      description: "The currency to convert from."
    }),
  ],
  resultType: sdk.ValueType.Number,
  examples: [
    { params: [10, "EUR"], result: 11.44 },
    { params: [12.25, "CAD"], result: 9.80 },
  ],
  // ...
});
```

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

### D&D Pack Setup

Source: https://github.com/coda/packs-sdk/blob/main/docs/samples/full/dnd.md

Initializes the Coda Pack SDK, defines a batch size for API requests, and adds the D&D 5e API domain to the allowed network domains. This setup is required for all pack functionality.

```typescript
import * as sdk from "@codahq/packs-sdk";
export const pack = sdk.newPack();

// How many spells to fetch in each sync formula execution.
const BATCH_SIZE = 20;

// Allow requests to the DND API.
pack.addNetworkDomain("dnd5eapi.co");

```

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

### Set Up Environment with nvm

Source: https://github.com/coda/packs-sdk/blob/main/CONTRIBUTING.md

Use nvm to manage Node.js versions and source the setup script for the packs-sdk repo.

```shell
source setup-env.sh
```

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

### HeaderBearerTokenAuthentication Setup

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/interfaces/HeaderBearerTokenAuthentication.md

Demonstrates how to set up HeaderBearerToken authentication in a Coda Pack.

```APIDOC
## HeaderBearerTokenAuthentication

Authenticate using an HTTP header of the form `Authorization: Bearer <token>`.

### Usage

```ts
pack.setUserAuthentication({
  type: sdk.AuthenticationType.HeaderBearerToken,
});
```

### Properties

- **type**: `HeaderBearerToken` - Identifies this as HeaderBearerToken authentication.
- **endpointDomain?**: `string` - The root domain that all endpoints share when `requiresEndpointUrl` is true.
- **getConnectionName?**: `MetadataFormula` - A function that returns a name for the account to label it in the UI.
- **instructionsUrl?**: `string` - A link to a help article with instructions on how to set up an account.
- **networkDomain?**: `string` | `string[]` - Which domain(s) should get auth credentials when a pack is configured with multiple domains.
- **postSetup?**: `SetEndpoint[]` - One or more setup steps to run after the user has set up the account.
- **requiresEndpointUrl?**: `boolean` - If true, indicates this pack has a specific endpoint domain for each account.
```

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

### Example RequestHandlerTemplate Configuration

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/interfaces/RequestHandlerTemplate.md

This example demonstrates how to configure a RequestHandlerTemplate for a 'FetchWidget' formula. It includes parameter definitions, request method, URL with path parameters, name mapping for query parameters, and a transformation function for the output format.

```typescript
sdk.makeTranslateObjectFormula({
  name: "FetchWidget",
  description: "Fetches a widget.",
  parameters: [
    sdk.makeParameter({type: sdk.ParameterType.String, name: "id"}),
    sdk.makeParameter({type: sdk.ParameterType.String, name: "outputFormat"}),
  ],
  request: {
    method: "GET",
    url: "https://example.com/api/widgets/{id}",
    nameMapping: {outputFormat: "format"},
    transforms: {
      format: function(value) {
        return value.toLowerCase();
      },
    },
    queryParams: ["format"],
  },
});
```

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

### Basic GET Request

Source: https://github.com/coda/packs-sdk/blob/main/docs/samples/topic/fetcher.md

Demonstrates the basic structure of a GET request using the fetcher.

```ts
let response = await context.fetcher.fetch({
  method: "GET",
  url: "https://example.com",
});
let data = response.body;
```

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

### Handling Optional Parameters in Examples

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/blocks/formulas.md

When defining examples, pass parameter values in the order they are defined. Include all required parameters. Pass `undefined` for any optional parameters you wish to skip.

```typescript
examples: [
  // Set only the first parameter.
  { params: ["Hello"], result: "HELLO!!!" },
  // Set the first and third parameter.
  { params: ["Hello", undefined, "?"], result: "HELLO???" },
],
```

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

### Setting up CodaApiBearerTokenAuthentication

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/interfaces/CodaApiBearerTokenAuthentication.md

Example of how to configure your pack to use Coda API bearer token authentication.

```APIDOC
## Setting up CodaApiBearerTokenAuthentication

### Description
This example demonstrates how to configure your pack to use the `CodaApiBearerTokenAuthentication` type. This authentication method is specifically designed for interacting with the Coda REST API and simplifies the process by allowing Coda to manage the API token generation and storage.

### Method
```ts
pack.setUserAuthentication({
  type: sdk.AuthenticationType.CodaApiHeaderBearerToken,
});
```

### Parameters
This method does not take any direct parameters in this simplified example, but it configures the pack's authentication to use the `CodaApiHeaderBearerToken` type.

### Request Example
```ts
pack.setUserAuthentication({
  type: sdk.AuthenticationType.CodaApiHeaderBearerToken,
});
```

### Response
This operation configures the pack's authentication settings and does not return a direct response in the context of the pack setup. The configuration is applied internally by the Coda SDK.
```

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

### Bootstrap Dependencies with Makefile

Source: https://github.com/coda/packs-sdk/blob/main/CONTRIBUTING.md

Install SDK dependencies using the Makefile's bootstrap script.

```shell
make bootstrap
```

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

### Install pipenv and set PATH

Source: https://github.com/coda/packs-sdk/blob/main/CONTRIBUTING.md

Install pipenv and add it to your PATH when using Google Cloud Shell.

```shell
pip install --user pipenv
export PATH=$HOME/.local/bin:$PATH
```

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

### Open Data NY Sync Table Example

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/blocks/sync-tables/index.md

This example demonstrates the implementation of a sync table for the Open Data NY data source. It showcases how to define and populate a sync table within a Coda Pack.

```typescript
--8<-- "samples/packs/dynamic-sync-table/open_data_ny.ts"
```

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

### Custom Authentication Example

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/interfaces/CustomAuthentication.md

Demonstrates how to configure and use custom authentication with template replacement for API requests. This example shows inserting secret IDs into the URL and secret values into the body and headers.

```typescript
execute: async function([], context) {
  let secretIdTemplateName = "secretId-" + context.invocationToken;
  let urlWithSecret = "/api/entities/{{" + secretIdTemplateName + "}}"
  let secretValueTemplateName = "secretValue-" + context.invocationToken;
  let secretHeader = "Authorization  {{" + secretValueTemplateName + "}}";
  let bodyWithSecret = JSON.stringify({
    key: "{{" + secretValueTemplateName + "}}",
    otherBodyParam: "foo",
  });

  let response = await context.fetcher.fetch({
    method: "GET",
    url: urlWithSecret,
    body: bodyWithSecret,
    headers: {
      "X-Custom-Authorization-Header": secretHeader,
    },
  });
  // ...
}
```

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

### Creating an ImageAttributionNode

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/interfaces/ImageAttributionNode.md

Example of how to create an ImageAttributionNode using the SDK.

```APIDOC
## Function: makeAttributionNode

### Description
Creates an attribution node that renders as a hyperlinked image.

### Parameters
#### Object Parameters
- **type** (AttributionNodeType.Image) - Required - Identifies this as an image attribution node.
- **anchorUrl** (string) - Required - The URL to link to.
- **imageUrl** (string) - Required - The URL of the image to render.

### Request Example
```javascript
sdk.makeAttributionNode({
  type: sdk.AttributionNodeType.Image,
  anchorUrl: "https://example.com",
  imageUrl: "https://example.com/assets/logo.png",
});
```
```

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

### Example API Endpoint for Books

Source: https://github.com/coda/packs-sdk/blob/main/docs/tutorials/build/sync-table.md

This is the base URL for the Gutendex API to retrieve book data.

```bash
https://gutendex.com/books
```

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

### Add Pack Boilerplate

Source: https://github.com/coda/packs-sdk/blob/main/docs/tutorials/build/formula.md

Start any new Pack by importing the SDK and creating a Pack definition.

```typescript
import * as sdk from "@codahq/packs-sdk";
export const pack = sdk.newPack();
```

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

### Creating a Link Attribution Node

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/interfaces/LinkAttributionNode.md

This example demonstrates how to use `sdk.makeAttributionNode` to create a link attribution node.

```APIDOC
## Create Link Attribution Node

### Description
Creates an attribution node that renders a hyperlink.

### Method
`sdk.makeAttributionNode`

### Parameters
#### Properties
- **type** (AttributionNodeType.Link) - Required - Identifies this as a link attribution node.
- **anchorUrl** (string) - Required - The URL to link to.
- **anchorText** (string) - Required - The text of the hyperlink.

### Request Example
```javascript
sdk.makeAttributionNode({
  type: sdk.AttributionNodeType.Link,
  anchorUrl: "https://example.com",
  anchorText: "Data provided by ExampleCorp."
});
```
```

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

### Example API Response for Last Page

Source: https://github.com/coda/packs-sdk/blob/main/docs/tutorials/build/sync-table.md

Illustrates the API response when there are no more pages of results. The 'next' link is null in this case.

```json
{
  "count": 308,
  "next": null,
  "previous": "https://gutendex.com/books/?page=9&topic=Cooking",
  "results": [
    // ...
  ]
}
```

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

### Example API Endpoint

Source: https://github.com/coda/packs-sdk/blob/main/docs/tutorials/build/fetcher.md

This is the URL for the ExchangeRate-API endpoint to get the latest exchange rates for CAD.

```text
https://open.er-api.com/v6/latest/CAD
```

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

### Create and navigate to a new Pack directory

Source: https://github.com/coda/packs-sdk/blob/main/docs/tutorials/get-started/cli.md

Before installing the SDK and creating a Pack, ensure you are working in a clean directory. Use these commands to create a new directory and change into it.

```sh
mkdir my-pack
cd my-pack
```

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

### Throwing a UserVisibleError

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/classes/UserVisibleError.md

Throw a UserVisibleError when a formula encounters an issue and you want to display a user-friendly message in the UI. This example checks if a URL starts with 'https://' and throws an error if it does not.

```typescript
if (!url.startsWith("https://")) {
  throw new sdk.UserVisibleError("Please provide a valid url.");
}
```

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

### Initialize a new Pack project

Source: https://github.com/coda/packs-sdk/blob/main/docs/tutorials/get-started/cli.md

After creating a directory, initialize your project using npm. This sets up the basic `package.json` file.

```sh
npm init
```

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

### Set up Pack Authentication

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/development/cli.md

Use this command to initiate the authentication setup for a specific Pack. The CLI will prompt for necessary credentials based on your Pack's authentication definition.

```sh
npx packs auth path/to/pack.ts
```

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

### Preview Documentation Locally

Source: https://github.com/coda/packs-sdk/blob/main/CONTRIBUTING.md

Run the MkDocs preview server to view documentation changes locally on localhost:8000.

```shell
make view-docs
```

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

### CustomHeaderTokenAuthentication Example

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/interfaces/CustomHeaderTokenAuthentication.md

Example of how to configure CustomHeaderToken authentication in your Coda pack.

```APIDOC
## CustomHeaderTokenAuthentication

Authenticate using an HTTP header with a custom name and token prefix that you specify.

### Configuration Example

```ts
pack.setUserAuthentication({
  type: sdk.AuthenticationType.CustomHeaderToken,
  headerName: "X-API-Key",
});
```

### Properties

*   **type** (AuthenticationType.CustomHeaderToken) - Required - Identifies this as CustomHeaderToken authentication.
*   **headerName** (string) - Required - The name of the HTTP header.
*   **tokenPrefix** (string) - Optional - An optional prefix in the HTTP header value before the actual token. The HTTP header will be of the form `<headerName>: <tokenPrefix> <token>`.
*   **endpointDomain** (string) - Optional - The root domain that all endpoints share, used when `requiresEndpointUrl` is true.
*   **requiresEndpointUrl** (boolean) - Optional - If true, indicates this pack has a specific endpoint domain for each account.
*   **getConnectionName** (MetadataFormula) - Optional - A function that returns a name for the account to label it in the UI.
*   **instructionsUrl** (string) - Optional - A link to a help article with more instructions about setting up an account.
*   **networkDomain** (string | string[]) - Optional - Which domain(s) should get auth credentials.
*   **postSetup** (SetEndpoint[]) - Optional - Setup steps to run after the user has set up the account.
```

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

### CrawlStrategy Example

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/interfaces/CrawlStrategy.md

Example of a CrawlStrategy object defining a parent table relation.

```typescript
{
  parentTable: {
    tableName: "Projects",
    propertyKey: "id",
  },
}
```

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

### Example Weather Card Schema

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/blocks/cards.md

This example demonstrates how to define an object schema for a weather card, including properties and display configurations.

```typescript
import * as sdk from "@codahq/packs-sdk";

// This is a placeholder for the actual content of the weather.ts file.
// In a real scenario, this would contain the SDK code to define the weather card schema.
const WeatherCardSchema = sdk.makeObjectSchema({
  properties: {
    city: {
      type: sdk.ValueType.String,
      description: "The city where the weather is reported."
    },
    temperature: {
      type: sdk.ValueType.Number,
      codaType: sdk.ValueHintType.Temperature,
      description: "The current temperature."
    },
    condition: {
      type: sdk.ValueType.String,
      description: "The current weather condition (e.g., Sunny, Cloudy, Rainy)."
    },
    icon: {
      type: sdk.ValueType.String,
      format: "image_url",
      description: "URL to an icon representing the weather condition."
    }
  },
  displayProperty: "city",
  titleProperty: "city",
  subtitleProperties: ["temperature", "condition"],
  featuredProperties: ["city", "temperature", "condition", "icon"]
});

// Example of how this schema might be used in a formula:
// export async function getWeather(city: string): Promise<sdk.Object> {
//   // ... fetch weather data ...
//   const weatherData = { city: "Example City", temperature: 25, condition: "Sunny", icon: "http://example.com/icon.png" };
//   return { ...weatherData, codaType: "object", codaSchema: WeatherCardSchema };
// }
```

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

### Prompting User to Select Endpoint via SetEndpoint Post-Setup

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/basics/authentication/index.md

Implement a `SetEndpoint` post-setup step to allow users to choose from multiple available endpoints. The `getOptions` function dynamically fetches the list of endpoints from an API.

```typescript
pack.setUserAuthentication({
  // After approving access, the user should select which instance they want to
  // connect to.
  postSetup: [{
    type: sdk.PostSetupType.SetEndpoint,
    name: "SelectEndpoint",
    description: "Select the site to connect to:",
    // Generate the list of endpoint options.
    getOptions: async function (context) {
      // Make a request to the API to retrieve the sites they can access.
      let response = await context.fetcher.fetch({
        method: "GET",
        url: "https://api.example.com/my/sites",
      });
      let sites = response.body.sites;
      return sites.map(site => {
        return { display: site.name, value: site.url };
      });
    },
  }],
});
```

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

### Example: Step Diagram Formula

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/basics/parameters/index.md

This snippet is an example of a step diagram formula, likely demonstrating complex parameter usage or formula logic.

```typescript
--8<-- "samples/packs/parameter/steps.ts"
```

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

### Example Data URI for Embedded Images

Source: https://github.com/coda/packs-sdk/blob/main/docs/agents/features/chat.md

Display images embedded directly in the URL using the `data:` scheme. This example shows a base64-encoded SVG.

```plaintext
data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgMTAwIDEwMCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI1MCIgLz48L3N2Zz4=
```

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

### Todoist Task Formula Example

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/design.md

Example of a getter formula for a single Todoist task. Requires an API endpoint to retrieve an item by ID and the ID must be user-visible.

```http
GET https://api.todoist.com/rest/v2/tasks/<taskId>
```

```typescript
--8<-- "samples/packs/todoist/simple.ts:sync"
```

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

### Pack Setup and Authentication

Source: https://github.com/coda/packs-sdk/blob/main/docs/samples/full/todoist.md

Initializes the Todoist pack, sets the network domain, and configures OAuth2 authentication. The `getConnectionName` function fetches the user's full name for display.

```typescript
// #region Pack setup

export const pack = sdk.newPack();

pack.addNetworkDomain("todoist.com");

pack.setUserAuthentication({
  type: sdk.AuthenticationType.OAuth2,
  // OAuth2 URLs and scopes are found in the Todoist OAuth guide:
  // https://developer.todoist.com/guides/#oauth
  authorizationUrl: "https://todoist.com/oauth/authorize",
  tokenUrl: "https://todoist.com/oauth/access_token",
  scopes: ["data:read_write"],
  scopeDelimiter: ",",

  // Determines the display name of the connected account.
  getConnectionName: async function (context) {
    let url = sdk.withQueryParams("https://api.todoist.com/sync/v9/sync", {
      resource_types: JSON.stringify(["user"]),
    });
    let response = await context.fetcher.fetch({
      method: "GET",
      url: url,
    });
    return response.body.user?.full_name;
  },
});

// #endregion
```

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

### Generate Pack file structure

Source: https://github.com/coda/packs-sdk/blob/main/docs/tutorials/get-started/cli.md

Use the `packs init` command to create the basic file structure for your Pack based on a template. This is a quick way to start your project.

```sh
npx packs init
```

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

### Build the SDK

Source: https://github.com/coda/packs-sdk/blob/main/CONTRIBUTING.md

Perform a full build of the SDK to ensure core functionality is not broken.

```shell
make build
```

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

### Full Code for Sync Table Build

Source: https://github.com/coda/packs-sdk/blob/main/docs/tutorials/build/sync-table.md

This snippet contains the complete code for building and setting up the sync table as demonstrated in the tutorial. Ensure all necessary imports and configurations are present for it to function correctly.

```typescript
--8<-- "samples/packs/tutorials/sync-table/build1.ts"
```

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

### Todoist Tasks Sync Table Example

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/design.md

Example of a sync table for Todoist tasks. The API endpoint supports filtering parameters for targeted syncs. Use continuations for paginated results.

```http
GET https://api.todoist.com/rest/v2/tasks?
    project_id=<project ID>& 
    section_id=<section ID>& 
    label=<label name>& 
    filter=<filter string>& 
    lang=<language code>& 
    ids=<list of IDs>
```

```typescript
--8<-- "samples/packs/todoist/simple.ts:sync"
```

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

### Create a new Pack and add a Network Domain

Source: https://github.com/coda/packs-sdk/blob/main/docs/tutorials/build/sync-table.md

Initialize a new pack and add a network domain. This is a prerequisite for adding sync tables.

```typescript
import * as sdk from "@codahq/packs-sdk";
export const pack = sdk.newPack();

pack.addNetworkDomain("gutendex.com");

const BookSchema = sdk.makeObjectSchema({

});

pack.addSyncTable({
  name: "Books",
  description: "Lists books in the collection.",
  identityName: "Book",
  schema: BookSchema,
  // ...
});
```

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

### Get local date for calculations

Source: https://github.com/coda/packs-sdk/blob/main/docs/samples/topic/dates.md

Use this formula to get a date in the document's timezone for calculations. It formats the date to extract the year and checks if it contains at least two zeros.

```typescript
import * as sdk from "@codahq/packs-sdk";
export const pack = sdk.newPack();

pack.addFormula({
  name: "GoodNYEGlasses",
  description: "Determines if a date is good for New Years Eve glasses " +
    "(the year contains two zeros).",
  parameters: [
    sdk.makeParameter({
      type: sdk.ParameterType.Date,
      name: "date",
      description: "The input date.",
    }),
  ],
  resultType: sdk.ValueType.Boolean,
  execute: async function ([date], context) {
    // Format the JavaScript Date into a four-digit year.
    let formatted = date.toLocaleDateString("en", {
      timeZone: context.timezone, // Use the timezone of the doc (important!).
      year: "numeric",
    });
    // Extract all of the zeros from the year.
    let zeros = formatted.match(/0/g);
    return zeros?.length >= 2;
  },
});
```

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

### Initialize Pack and Network Domain

Source: https://github.com/coda/packs-sdk/blob/main/docs/samples/full/github.md

Sets up the Coda Pack, defines a regular expression for parsing GitHub repo URLs, and allows the Pack to access the github.com domain.

```typescript
import * as sdk from "@codahq/packs-sdk";
export const pack = sdk.newPack();

// Regular expression used to parse repo URLs.
const RepoUrlRegex = new RegExp("^https://github.com/([^/]+)/([^/]+)");

// How many items to fetch per-page when making API list requests.
const PageSize = 50;

// Allow the Pack to access the GitHub domain.
pack.addNetworkDomain("github.com");

```

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

### Todoist Task Column Format Example

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/design.md

Example of a column format for Todoist tasks. This enriches simple values in tables with rich data and requires a getter formula that accepts a single parameter.

```typescript
--8<-- "samples/packs/todoist/simple.ts:format"
```

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

### Example API Endpoint with Topic Filter

Source: https://github.com/coda/packs-sdk/blob/main/docs/tutorials/build/sync-table.md

Demonstrates how to filter book results by a specific topic using a query parameter.

```bash
https://gutendex.com/books?topic=Cooking
```

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

### Todoist AddTask Action Formula Example

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/design.md

Example of an action formula to add a new task in Todoist. Action formulas are used for API calls with side effects, such as creating, updating, or deleting items.

```http
POST https://api.todoist.com/rest/v2/tasks
{
  "content": "Buy milk"
}
```

```typescript
--8<-- "samples/packs/todoist/simple.ts:action"
```

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

### Minimal Hello World Formula

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/basics/parameters/index.md

A basic example of a Coda formula that accepts a string parameter and returns a greeting. This demonstrates the simplest use case for string parameters.

```typescript
--8<-- "samples/packs/hello_world/minimal.ts"
```

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

### Define a Dynamic Sync Table

Source: https://github.com/coda/packs-sdk/blob/main/docs/guides/blocks/sync-tables/dynamic.md

Use `addDynamicSyncTable` to define a sync table whose schema can adapt. Provide a name, identity, and functions to list dynamic URLs, get the table name, get the schema, and sync rows.

```typescript
pack.addDynamicSyncTable({
  name: "Tasks",
  description: "The tasks in the selected project.",
  identityName: "Task",
  listDynamicUrls: async function (context) {
    // Return the datasets the user has access to.
    // ...
  },
  getName: async function (context) {
    // Return the name of the selected dataset.
    // ...
  },
  getDisplayUrl: async function (context) {
    // Return a display URL for the selected dataset.
    // ...
  },
  getSchema: async function (context) {
    // Return a schema for the selected dataset.
    // ...
  },
  formula: {
    // Sync the rows from the dataset.
    // ...
  },
});
```

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

### Provide LLM Instructions for Formulas and Parameters

Source: https://github.com/coda/packs-sdk/blob/main/docs/agents/upgrade.md

Use the `instructions` field to provide alternate descriptions for LLMs to reliably understand how to use formulas and parameters. This is especially useful when the default description might be ambiguous for an LLM.

```typescript
pack.addFormula({
  name: "CreateContact",
  description: "Creates a new contact.",
  instructions: `
    Creates a new contact for a given customer.
    The contact should be an individual who works at the company.
    To save the contact information for the business as a whole, use the
    UpdateCustomer formula instead.
  `,
  parameters: [
    sdk.makeParameter({
      type: sdk.ParameterType.String,
      name: "name",
      description: "The name of the contact.",
      instructions: `
        The name of the contact.
        If available, provide the full name (first, middle, and last).
        Don't include prefixes and suffixes (Dr., Esq., etc.).
      `,
    }),
    // ...
  ],
  resultType: sdk.ValueType.String,
  execute: async function (args, context) {
    // ...
  },
});
```

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

### WebBasicAuthentication Configuration

Source: https://github.com/coda/packs-sdk/blob/main/docs/reference/sdk/core/interfaces/WebBasicAuthentication.md

Example of how to configure WebBasic authentication in a Coda pack.

```APIDOC
## Interface: WebBasicAuthentication

Authenticate using HTTP Basic authorization. The user provides a username and password
(sometimes optional) which are included as an HTTP header according to the Basic auth standard.

### Properties

- **type**: `WebBasic` - Identifies this as WebBasic authentication.
- **endpointDomain?**: `string` - The root domain that all endpoints share when `requiresEndpointUrl` is true.
- **getConnectionName?**: `MetadataFormula` - A function that returns a name for the account to label it in the UI.
- **instructionsUrl?**: `string` - A link to a help article with more instructions.
- **networkDomain?**: `string` | `string[]` - Which domain(s) should get auth credentials.
- **postSetup?**: `SetEndpoint[]` - Setup steps to run after the user has set up the account.
- **requiresEndpointUrl?**: `boolean` - If true, indicates this pack has a specific endpoint domain for each account.
- **uxConfig?**: `object` - Configuration for labels to show in the UI.
  - **placeholderPassword?**: `string` - A placeholder value for the password input.
  - **placeholderUsername?**: `string` - A placeholder value for the username input.
  - **usernameOnly?**: `boolean` - If true, only a username input will be shown.

## Example

```ts
pack.setUserAuthentication({
  type: sdk.AuthenticationType.WebBasic,
});
```
```

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

### Importing the Superhuman Packs SDK

Source: https://github.com/coda/packs-sdk/blob/main/docs/blog/posts/sdk_rename.md

New code examples will import the library as `sdk` for consistency with the new branding. Existing code importing it as `coda` will continue to function without changes.

```typescript
import * as sdk from "@codahq/packs-sdk";

export const pack = sdk.newPack();
```

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

### Get Dataset by ID

Source: https://github.com/coda/packs-sdk/blob/main/docs/samples/topic/dynamic-sync-table.md

Retrieves a dataset by its ID from the Socrata API.

```typescript
async function getDataset(context: sdk.SyncExecutionContext):
  Promise<Dataset> {
  let datasetUrl = context.sync.dynamicUrl;
  let datasetId = getDatasetId(datasetUrl);
  let url = `https://${Domain}/api/views/${datasetId}.json`;
  let response = await context.fetcher.fetch({
    method: "GET",
    url: url,
  });
  return response.body;
}
```