@epcc-sdk/sdks-files
v0.5.1
Published
A TypeScript client for the Elastic Path files API. The functions, types and Zod schemas are generated from the OpenAPI spec of the API.
Readme
@epcc-sdk/sdks-files
A TypeScript client for the Elastic Path files API. The functions, types and Zod schemas are generated from the OpenAPI spec of the API.
Installation
npm install @epcc-sdk/sdks-filesQuick start
import { createFilesClient, getAllFiles } from "@epcc-sdk/sdks-files"
const client = createFilesClient({
baseUrl: "https://euwest.api.elasticpath.com",
clientId: process.env.EPCC_CLIENT_ID!,
clientSecret: process.env.EPCC_CLIENT_SECRET!,
})
const { data, error } = await getAllFiles({ client })The client gets an access token and adds it to each request. It gets a new token before the token expires. After a 401 response, it gets a new token and sends the request one more time. After a 408 or 429 response, or after some server and network errors, it waits and sends the request again.
Pass the client to each operation. The package also exports a client that has no credentials. If you call an operation without { client }, it uses that client and the API returns a 401 response.
A failed request does not throw. The operation returns the error in error. To make operations throw, add config: { throwOnError: true } to the factory options.
Base URL
Set baseUrl to the API host of your region, with no path. Each operation adds its own path.
Credentials
| Option | Grant type |
| ----------------------------- | ---------------------------------------------------------------------------------------- |
| clientId and clientSecret | Client credentials. Use it only on a server, because it contains a secret. |
| clientId | Implicit. You can use it in a browser. |
| token | A token that you got yourself. The client cannot replace it, so a 401 response is final. |
| provider | Your own TokenProvider function. |
| source | A TokenSource that you keep, for example to clear the token when a user signs out. |
These options change the default behavior:
| Option | What it does |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| storage | Where the client keeps the token. The default is memoryStorage. localStorageAdapter keeps the token across page loads and browser tabs. |
| leewaySeconds | How many seconds before expiry the client gets a new token. |
| retry | The options of createRetryFetch. Set it to false to stop the retries. |
| fetch | The fetch function that the client uses for all requests, including token requests. |
| config | Client configuration, for example headers. It overrides the values that the factory sets. |
Upload a file
createAFile sends the file in a multipart request. Give the file as a File in body.file. The name of the File becomes the name of the file in Elastic Path.
import { readFile } from "node:fs/promises"
import { createAFile } from "@epcc-sdk/sdks-files"
const file = new File([await readFile("photo.png")], "photo.png", {
type: "image/png",
})
const { data, error } = await createAFile({ client, body: { file } })In a browser, use the File from an <input type="file"> element. In Node, File is global in version 20 and later.
For a file that is already at a URL, give the URL in body.file_location and do not send body.file.
Make the client yourself
The package exports the parts that the factory uses. Use them when you need your own token source or your own fetch.
import {
clientCredentialsProvider,
createAuthCallback,
createAuthenticatedFetch,
createClient,
createConfig,
createRetryFetch,
createTokenSource,
} from "@epcc-sdk/sdks-files"
const source = createTokenSource(
clientCredentialsProvider({
baseUrl: "https://euwest.api.elasticpath.com",
clientId: process.env.EPCC_CLIENT_ID!,
clientSecret: process.env.EPCC_CLIENT_SECRET!,
}),
)
const client = createClient(
createConfig({
baseUrl: "https://euwest.api.elasticpath.com",
auth: createAuthCallback(source),
fetch: createRetryFetch({ fetch: createAuthenticatedFetch(source) }),
}),
)- Make both wrappers from the same
source.createAuthenticatedFetchreplaces only a token that came from its own source. - Put
createAuthenticatedFetchinsidecreateRetryFetch. In the other order, each retry sends the expired token again.
Do not add the token with a request interceptor. An interceptor cannot see the response, so it cannot get a new token after a 401 response.
Zod schemas
The ./zod export has a Zod schema for each request and response. zod 4 is an optional peer dependency, so the main export does not import it.
import { zGetAllFilesResponse } from "@epcc-sdk/sdks-files/zod"
const result = zGetAllFilesResponse.safeParse(data)A field that the spec gives as int64 is a number in the types and in the schemas.
MCP tools
The ./mcp export has one Model Context Protocol (MCP) tool for each operation, for MCP SDK v2. You need zod 4 and @modelcontextprotocol/server 2 only for this export.
import { McpServer } from "@modelcontextprotocol/server"
import { tools } from "@epcc-sdk/sdks-files/mcp"
const server = new McpServer({ name: "files", version: "1.0.0" })
for (const tool of tools({ client })) {
server.registerTool(tool.name, tool.config, tool.handler)
}- Each tool sends its requests with the client that you give it. To send a header with each request, such as
EP-Store-Id, set it inconfig.headersof the client. - For one tool, use its factory. The name of the factory is the operation name with
Tooladded, for examplegetAllFilesTool. - The name of a tool is
files_and the operation name in snake case, for examplefiles_get_all_files. - The arguments of a tool are in
path,query,headersandbody. TheAuthorizationheader comes from the client. tool.config._meta["com.elasticpath/operation"].riskisread,create,updateordelete. The tool annotations come from it. To register only the read tools, keep the tools whereriskisread.- A tool returns an API error as an
isErrorresult. It does not throw.
files_create_a_file uploads a file. Give the file in file as a data: URI, for example data:<media type>;base64,<data>, and its name in file_name. The largest file is 8,388,608 bytes (8 MiB). The limit is the default limit of the API. If the file is larger, the URI is not valid, or the value is a URL, the tool returns an isError result and sends nothing. The tool never downloads a URL.
