# @artworker/sdk

> Javascript SDK for the Artworker API and artwork upload system.

Latest version **0.0.5** (published 2023-09-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install @artworker/sdk
pnpm add @artworker/sdk
yarn add @artworker/sdk
bun add @artworker/sdk
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.5 |
| Published | 2023-09-08 |
| First published | 2023-08-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 3 |
| Unpacked size | 3.2 MB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | Jack Harley |
| Maintainers | 02harlxj |
| Keywords | typescript-template, npm-boilerplate, semantic-release-boilerplate |

## Links

- npm: https://www.npmjs.com/package/@artworker/sdk
- Repository: https://bitbucket.org/kudouk/artworker-sdk
- Issues: https://bitbucket.org/kudouk/artworker-sdk/issues
- npm.io page: https://npm.io/package/@artworker/sdk

## Dependencies (3)

- [auth0-js](https://npm.io/package/auth0-js.md) ^9.22.1
- [auth0-lock](https://npm.io/package/auth0-lock.md) ^12.1.0
- [jsonschema](https://npm.io/package/jsonschema.md) ^1.4.1

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 0.0.5 (latest) — 2023-09-08
- 0.0.6-beta.1 (beta) — 2024-04-08
- 0.0.4 — 2023-09-04
- 0.0.3 — 2023-09-01
- 0.0.2 — 2023-09-01
- 0.0.1 — 2023-08-31

## README

# Artworker SDK Documentation

## Table of Contents
- [Artworker SDK Documentation](#artworker-sdk-documentation)
  - [Table of Contents](#table-of-contents)
  - [Introduction](#introduction)
  - [Installation](#installation)
  - [Artworker Client](#artworker-client)
      - [Throws](#throws)
    - [Methods](#methods)
      - [`picker(options?: PickerOptions): Picker`](#pickeroptions-pickeroptions-picker)
  - [Picker](#picker)
    - [PickerOptions](#pickeroptions)
      - [`uploadMeta`](#uploadmeta)
      - [`onClose`](#onclose)
      - [`onOpen`](#onopen)
      - [`onDone`](#ondone)
    - [Methods](#methods-1)
      - [`open(): void`](#open-void)
    - [Events](#events)
- [Authentication](#authentication)
  - [The Auth Object](#the-auth-object)
    - [Methods](#methods-2)
    - [Usage Example](#usage-example)

## Introduction

The Artworker SDK allows your B2B SaaS to integrate with Artworker services, making it easier to handle artwork. This documentation aims to provide a comprehensive guide for implementing the SDK's features.

## Installation

```bash
npm install artworker-sdk
```

## Artworker Client

```typescript
const client = new Client('your-api-key');
```

#### Throws

- Throws an error if the `apiKey` is not supplied or invalid.

### Methods

#### `picker(options?: PickerOptions): Picker`

Initializes a new `Picker` instance, allowing a user to upload artwork. See below for more details.

## Picker

```typescript
const client = new Client('your-api-key');

const picker = artworker.picker({
  uploadMeta: {
    customUId: "wedk3w4f", // the Id of the orderItem or orderId in your system (if you have it)
    jobName: "300 flyers",
    customerEmail: "joe@bloggs.com",
    customerName: "Joe Bloggs",
  },
  onClose: () => {
    console.log("user closed picker widget without submitting artwork");
  },
  onDone: (pickerResponse) => {
    console.log("user submitted the following artwork:", pickerResponse);
  },
});

// open the picker
picker.open();
```

### PickerOptions
Configure callbacks to handle events from the Artworker picker widget

```typescript
interface PickerOptions {
  uploadMeta: {
    customUId: string; // the Id of the orderItem or orderId in your system (if you have it)
    jobName: string;
    customerEmail: string;
    customerName: string;
  };
  onClose?: () => void;
  onOpen?: (handle: PickerInstance) => void;
  onDone?: (files: PickerResponse) => void;
}
```
#### `uploadMeta`
Prefills fields in artworker based on input

#### `onClose`
Called when the picker is closed by the user, without submitting any artwork

#### `onOpen`
Prefills fields in artworker based on input

#### `onDone`
Called when the user has submitted artwork. Returns the `PickerResponse` object
```typescript
interface PickerResponse {
  fileTransfer?: FileTransfer;
}

interface Image {
  id: bigint;
  url: string;
  filename: string;
  contentType: string;
}

interface Media {
  id: bigint;
  url: string;
  filename: string;
  contentType: string;
  thumbnail?: Image;
  imagePreview?: Image;
  originalFilename: string;
  fileSize: string;
}

interface FileTransfer {
  id: string;
  mediaItems: Media[];
  contactName: string;
  contactEmail: string;
  orderRef: string;
  name: string;
  notes: string;
}
```

### Methods

#### `open(): void`

Opens the Picker UI.

### Events

- `opened`: Triggered when the picker is opened.
- `done`: Triggered when the picker process is done.
- `closed`: Triggered when the picker is closed.

# Authentication
If your company operates as a B2B SaaS and some of your customers have Artworker accounts, you'll need to obtain their public API keys to capture artwork on their behalf. You have two options for achieving this:

1. Request that your customers manually go to their Artworker account, copy their public API key, and share it with you through a secure channel of your choice.
2. Use the Auth method provided in this class to automate the acquisition of their public API key.
   
## The Auth Object

```javascript
import { Auth } from '@artworker/sdk';
const auth = new Auth({ debugMode: true });
```

### Methods

| Method                                       | Description                                                                    |
| -------------------------------------------- | ------------------------------------------------------------------------------ |
| `show()`                                     | Displays the authentication widget.                                            |
| `onAuthenticated(cb: AuthentiationCallback)` | Sets the callback function that will be called upon successful authentication. |
| `onError(cb: ErrorCallback)`                 | Sets the callback function that will be called when an error occurs.           |

### Usage Example

A sample code snippet on how to use the Auth class is provided below:

```javascript
import { Auth } from '@artworker/sdk';
const auth = new Auth({ debugMode: true });

auth.onAuthenticated((apiKey) => {
  console.log('Authenticated, received API Key:', apiKey);
});

auth.onError((err) => {
  console.error('Error:', err);
});

auth.show();
```

---
_Source: https://npm.io/package/@artworker/sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._