@amplience/image-studio-sdk

Official SDK for embedding Amplience Image Studio

This SDK is designed to help embed the Amplience Image Studio into business admin interfaces, allowing merchants, marketers and authors to generate images as part of their existing tools and workflow.

Installation

Using npm:

npm install @amplience/image-studio-sdk --save

Usage

ES6:

import { AmplienceImageStudio } from '@amplience/image-studio-sdk';

const sdk = new AmplienceImageStudio();

CommonJS:

const { AmplienceImageStudio } = require('@amplience/image-studio-sdk');

const sdk = new AmplienceImageStudio();

Creating a global instance of AmplienceImageStudio is advised against, and a new one should be created for each interaction due to shared promise management you may get expected results if you make asynchronous interactions with the same instance.

AmplienceImageStudio - Quick Start

Image Studio Actions

Each action contains a default set of behavioural options:

| Action | Options | |:----------|:-| | editImages | allowImageSave: trueallowLogout: falseallowCreate: false | | launch | allowImageSave: falseallowLogout: trueallowCreate: true |

The user can override the default action behaviours by adding the relevant options to the sdkMetadataOverride member found within AmplienceImageStudioOptions

Edit Images

Image Studio expects an array of images for editing, once the user has editied the images and clicked 'Save Image', the resultant image will be returned within the response object and the Image Studio window will be closed.

Note: Image Studio currently only uses the first image you submit via this call

const sdk = new AmplienceImageStudio({
    domain: IMAGE_STUDIO_DOMAIN,
});
const response = await sdk.editImages([{
    url: 'https://url-to-your-image',
    name: 'image-name',
    mimeType: 'image/jpeg',
}]);

if(response.reason == ImageStudioReason.IMAGE) {
    console.log(response.image);
    // Example Image Response
    // {
    //     url: 'https://url-to-your-updated-image',
    //     name: 'updated-image-name',
    //     mimeType: 'image/jpeg',
    // }
}

Launch

Launches an Image Studio session standalone, which allows the user to select their own image for editing. Users are not able to save content back to their application and will only be able to download their creations locally.

const sdk = new AmplienceImageStudio({
    domain: IMAGE_STUDIO_DOMAIN,
});
const response = await sdk.launch();

if(response.reason == ImageStudioReason.CLOSED) {
    console.log("Success");
}

AmplienceImageStudioOptions

When creating an AmplienceImageStudio instance, the constructor takes an AmplienceImageStudioOptions object. This defines several options for customizing the behaviour of the studio:

| Key | Description | Default | Optional | |:----------|:-------------|:-:|:-:| | domain | base domain for your image-studio deployment | - | No | | sdkMetadataOverride | object containing behavioural overrides for image-studio SDKMetadata | {} | Yes | | windowTarget | window.open() target override, please see MDN | '_blank' | Yes | | windowFeatures | window.open() windowFeatures override, please see MDN | '' | Yes |

SDKMetadata

This SDK controls certain behaviours within image-studio through optional enablement flags.

Failing to submit an option to image-studio will not result in any bad behaviour. Image-Studio determines and controls the default behaviour of every option, however the structure and options available are controlled by this SDK.

| Option | Description | Default | |:----------|:-|:-:| | allowImageSave | allows content to be saved back to the SDK | false | | allowLogout | allows users to logout | true | | allowCreate | allows users to create new content | true | |orgId*| user organisation ID (used for entitlements and credit consumption) | ''

Along with the above options, some properties can be set following the builder pattern:

const sdk = new AmplienceImageStudio({domain: IMAGE_STUDIO_DOMAIN})
    .withDecodedOrgId('Org_Exampleid');

Here are the options that use this approach:

| Option | Description | Default | |:----------|:-|:-:| | .withEncodedOrgId('b3JnYW5pemF0aW9u') | - Set the user organisation to be used for entitlements and credit consumption. - must provide Base64 encoded ID i.e. GQL data| | | `.withDecodedOrgId('Org_Exampleid')` | - Set the user organisation to be used for entitlements and credit consumption. <br> - must provide plain text ID i.e. dc-extensions-sdk data| |

Releases

TLDR auto will perform automatic canary builds on push and the full release (including version bumping) during PR merge.

This project uses auto for the release process, a conventional commits plugin handles version bumping based on the commit history. Docs

The release process follows the configuration HERE

We have also included another plugin, protected-branch which works around the fact this repo contains branch protection on main. At the time of writing, this plugin isnot documented but the code can be found HERE

This project contains a Ruleset for main, with the following options enabled:

- Restrict creations
- restrict deletions
- block force pushes
- Requires a pull request before merging
    - approvals: 1
    - dismiss stale pull requests
    - require review from code owners
    - require conversation resolution before merging

In order to get around CODEOWNERS being required, we have followed the recommendations for adding @amplience/automation team as owners to package.json, package-lock.json and CHANGELOG.md - this allows auto to modify these at release time. The amp automation team also requires admin access to this github repo (repo -> settings -> collaborators and teams)

The release process requires a fine grained PAT token to perform the release process: this has been shared to this public repo through secrets.GH_PUBLIC_REPO_CONTENTS_ACCESS, the underlying token this references has been scoped to public repo's only. If this pattern is to be used against another project in future, and this is private, please add a PRIVATE variant of this PAT to cover private repos - otherwise add your project to the existing PAT token list of repositories. The purpose of GH_PUBLIC_REPO_CONTENTS_ACCESS secret is to cover only public repositories.

The initial part of the release process (checkouts, builds and package write) is controlled by the auto generate GH_TOKEN user, we have scoped this user with the correct permissions as found under permissions: within release.yml

The GH_PUBLIC_REPO_CONTENTS_ACCESS PAT is specificially used for the latter release portion (ie non-canary builds) and this user requires special privileges to perform package writes, changelog updates and commit's back to the repo itself (this is done via PR). At the time of writing the repository persmissions (through fine grained PAT) are:

- actions: read and write
- contents: read and write
- pull-requests: read and write
- issues: read
- metadata: read

License

This software is licensed under the Apache License, Version 2.0,

Copyright 2024 Amplience

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.