@fern-api/square-snippets

Square Snippets SDK

The Square Snippets SDK produces valid usage snippets from arbitrary request data.

Usage

The SDK can be used as follows:

import { SnippetResolver } from "@fern-api/square-snippets";

const resolver = new SnippetResolver({
  spec: {
    type: "openapi",
    openapi: {
        openapi: "3.0.0",
        info: {
            title: "Square API",
            version: "1.0.0",
        },
        paths: {
            ...
        }
    }
  }
});
const go = resolver.sdk("go");
const cards = go.endpoint("POST /v2/cards");
const response = await cards.generate({
    auth: {
        type: "bearer",
        token: "<YOUR_API_KEY>"
    },
    requestBody: {
        idempotency_key: "4935a656-a929-4792-b97c-8848be85c27c",
        source_id: "cnon:uIbfJXhXETSP197M3GB",
        card: {
            cardholder_name: "Amelia Earhart",
            billing_address: {
                address_line_1: "500 Electric Ave",
                address_line_2: "Suite 600",
                locality: "New York",
                administrative_district_level_1: "NY",
                postal_code: "10003",
                country: "US"
            },
            customer_id: "VDKXEEKPJN48QDG3BGGFAK05P8",
            reference_id: "user-id-1"
        }
    }
});

The generated response.snippet will be set to the following:

package example

import (
    client "github.com/square/square-go-sdk/client"
    option "github.com/square/square-go-sdk/option"
    context "context"
    square "github.com/square/square-go-sdk"
)

func do() () {
    client := client.NewClient(
        option.WithToken(
            "<YOUR_API_KEY>",
        ),
    )
    client.Cards.Create(
        context.TODO(),
        &square.CreateCardRequest{
            IdempotencyKey: "4935a656-a929-4792-b97c-8848be85c27c",
            SourceID: "cnon:uIbfJXhXETSP197M3GB",
            Card: &square.Card{
                CardholderName: square.String(
                    "Amelia Earhart",
                ),
                BillingAddress: &square.Address{
                    AddressLine1: square.String(
                        "500 Electric Ave",
                    ),
                    AddressLine2: square.String(
                        "Suite 600",
                    ),
                    Locality: square.String(
                        "New York",
                    ),
                    AdministrativeDistrictLevel1: square.String(
                        "NY",
                    ),
                    PostalCode: square.String(
                        "10003",
                    ),
                    Country: square.CountryUs.Ptr(),
                },
                CustomerID: square.String(
                    "VDKXEEKPJN48QDG3BGGFAK05P8",
                ),
                ReferenceID: square.String(
                    "user-id-1",
                ),
            },
        },
    )
}

Sync Methods

The SDK also exposes a generateSync method for users that don't have access to async and await in specific contexts. It uses the same parameters as generate and can be invoked like so:

import { SnippetResolver } from "@fern-api/square-snippets";

const resolver = new SnippetResolver({ ... });
const go = resolver.sdk("go");
const cards = go.endpoint("POST /v2/cards")
const response = cards.generateSync({ ... });

OpenAPI Endpoint Filtering

For performance, the endpoint method filters the provided OpenAPI document to only contain the selected endpoint (e.g. POST /v2/cards). This means you can reuse the filtered result with a simple variable for the endpoint like so:

// The 'cards' variable acts upon an OpenAPI document that only contains the 'POST /v2/cards' endpoint.
const cards = go.endpoint("POST /v2/cards")

// Generate multiple snippets using the same instance.
const one = cards.generateSync({ ... });
const two = cards.generateSync({ ... });
...

OpenAPI Overrides

You can override your own OpenAPI document in either the SnippetResolver constructor or in the sdk method like so:

import { SnippetResolver } from "@fern-api/square-snippets";

const resolver = new SnippetResolver({
  spec: {
    type: "openapi",
    openapi: {
        openapi: "3.0.0",
        info: {
            title: "Square API",
            version: "1.0.0",
        },
        paths: {
            ...
        }
    },
    overrides: {
        paths: {
            ...
        }
    }
  }
});