5.1.0 • Published 1 month ago

wrapsplash

Licence

MIT

Version

5.1.0

Deps

Size

3.3 MB

Vulns

Weekly

Stars

Summary Dependency Versions

WrapSplashTS v5.1.0

GitHub issues GitHub forks GitHub stars

WrapSplashTS is a simple, promise-based API wrapper for the popular Unsplash platform. The library is now written in TypeScript, bundled with Vite, and can be used in both Node.js and browser-based projects. Unsplash provides beautiful high quality free images and photos that you can download and use for any project without any attribution.

Before using the Unsplash API, you need to register as a developer and read the API Guidelines.

Note: Every application must abide by the API Guidelines. Specifically, remember to hotlink images and trigger a download when appropriate.

About
Installation
Sample Usage
Development
New API aliases
Dependency
Changelog
- v5.1.0
- v5.0.0
- v4.2.0
- v4.1.1
- v4.1.0
- v4.0.1
- v4.0.0
- v3.0.8
- v3.0.7
- v3.0.6
- v3.0.5
- v3.0.4
- v3.0.3
- v3.0.2
- v3.0.1
- v3.0.0
- v2.0.1
- v2.0.0
- v1.1.0
- v1.0.10
- v1.0.9
- v1.0.8
- v1.0.7
API Documentation
Continuous Integration (CI)
Tests
License
Acknowledgements

Installation

Install the package from NPM

npm install --save wrapsplash

The package exposes the main class through ES module and CommonJS entry points configured via the exports field in package.json.

Sample usage

// CommonJS
const WrapSplash = require('wrapsplash');

// ES modules
import WrapSplash from 'wrapsplash';

const unsplash = new WrapSplash();

unsplash.init({
  bearer_token: '<bearer-token>',
});

unsplash.getPhoto('<photo-id>')
  .then((result) => {
    console.log(result);
  })
  .catch((error) => {
    console.error(error);
  });

Development

npm install
npm run build
npm test
npm run test:coverage  # Generate coverage report
npm run lint

The package also includes a prepublish validation step that runs the build and tests before release.

Code Coverage

This project uses Vitest with V8 coverage provider to track test coverage. Coverage reports are automatically generated and uploaded to Codecov on every push to main or master branches via GitHub Actions CI.

View the latest coverage report:

To generate a local coverage report:

npm run test:coverage
# Coverage report will be generated in ./coverage directory

Current Coverage (v5.1.0)

Metric	Coverage	Threshold
Statements	97.8%	80%
Branches	79.5%	55%
Functions	98.4%	80%
Lines	97.8%	80%

Coverage thresholds (enforced):

Lines: 80%
Functions: 80%
Branches: 55%
Statements: 80%

New API aliases

The library now includes more descriptive convenience methods such as getPhoto, getRandomPhoto, createCollection, and updateCollection. The original method names remain available for backward compatibility.

Migration note: `createNewColection` → `createNewCollection`

The legacy method createNewColection (with misspelled "Colection") has been superseded by the correctly-spelled createNewCollection. The old method remains available as a deprecated alias for backward compatibility, but new code should use createNewCollection.

// Legacy (deprecated, but still works)
unsplash.createNewColection('My Collection');

// Recommended (new, correct spelling)
unsplash.createNewCollection('My Collection');

Response

200 OK

{
  "url": "https://images.unsplash.com/photo-1532800621406-0280a106eaa6?ixlib=rb-0.3.5&q=85&fm=jpg&crop=entropy&cs=srgb&s=70d0f9f241b88d82c7d0e52b93476e6a"
}

Dependency

This library depends on axios to make requests and generates required request headers for the Unsplash API.

Changelog

v5.1.0

Security: Removed crypto-js dependency (CVE-2023-46233), replaced with Node.js built-in crypto module
Added files field to package.json to prevent publishing unnecessary files to npm
Added smart retry logic with exponential backoff and Retry-After header support
Added retryable error filtering: only network errors, timeouts, 429, and 5xx responses are retried
Removed stale root index.js entry point in favor of package.json exports configuration
Removed crypto-js and @types/crypto-js from dependencies
Updated Security Policy: 5.0.x is now a supported version
Updated PR template to reference GitHub Actions instead of Travis/Circle CI
Expanded test suite from 32 to 109 tests with 97.8% statement coverage

v5.0.0

Rebranded project name from WrapSplashJS to WrapSplashTS to reflect TypeScript-first development
Fixed missing type definitions for WrapSplashResponse and WrapSplashError class
Updated Vite from 6.4.2 to 8.1.5 resolving security vulnerabilities in esbuild dependency
Updated TypeScript configuration: changed moduleResolution from deprecated "node" to "bundler" standard
Enhanced type safety with explicit WrapSplashResponse type for all API methods
Improved error handling with WrapSplashError class providing statusCode, statusText, and cause properties
Integrated Codecov for automated code coverage tracking via GitHub Actions
Added V8 coverage provider with multiple output formats (text, LCOV, JSON, HTML)
Enforced coverage thresholds: 80% lines/functions/statements, 55% branches

v4.2.0

Added clearer convenience methods such as getPhoto, getRandomPhoto, createCollection, and updateCollection
Preserved backward compatibility for the existing method names while introducing the newer API surface
Improved input validation for required parameters and unsupported option values
Added configurable request timeout support for network requests
Added ESLint configuration and a GitHub Actions CI workflow for automated build and test checks
Expanded regression coverage for the new aliases and validation behavior
Deprecation: The legacy method createNewColection (misspelled) is now deprecated; use createNewCollection instead (both methods remain functional for backward compatibility)

v4.1.1

Bumped package version for npm release
Updated README version and changelog entries
Fixed example entrypoint and constructor usage

v4.1.0

Migrated source to TypeScript
Switched bundler from Webpack to Vite
Updated tests to Vitest-compatible configuration
Dependency vulnerabilities audited and fixed

v4.0.1

Typos fixed
Dependency vulnerabilities audited and fixed

v4.0.0

Major refactorings
Updated documentation

v3.0.8

Dependency updates

v3.0.7

Library is now a UMD module, runs on client and server-side
Dependencies are now external
Compressed builds asset size reduced to 19KiB
AJAX migrated to Axios from fetch.
Tests migrated to Jest

v3.0.6

Compressed builds available
- Asset size reduced to 30.7KiB

v3.0.5

Updated Documentation
Updated dependencies
Code Quality improved
Dependency security aduits enabled

v3.0.4

Updated Documentation
Updated dependecies

v3.0.3

Updated dependecies

v3.0.2

Minor bug fix.

v3.0.1

Minor security fixes.
Minor bug fixes.
Code cleanups.
Updated documentations.
Test environment setup using Mochajs.
Assertion test specs added using Chaijs.
Strict server response validations added.

v3.0.0

Completely re-written in ES6 & ES7 specifications.
Continuous Integrations (CI) using modern Node.js workflows.
Minor bug fixes.
Major code optimizations.
Updated documentaions.
Major refactorings.
Now supports Yarn package manager
- https://yarnpkg.com/en/package/wrapsplash.
Now available at major CDNs:
- unpkg - https://unpkg.com/wrapsplash@3.0.0/.
- bundle.run - https://bundle.run/wrapsplash@3.0.0.
- jsDelivr - https://cdn.jsdelivr.net/npm/wrapsplash@3.0.0/.

v2.0.1

Minor bug fix.

v2.0.0

Documentation updated.
Added support for Collections APIs.
- Get a single page from the list of all collections - GET /collections.
- Get a single page from the list of featured collections - GET /collections/featured.
- Get a single page from the list of curated collections - GET /collections/curated.
- Retrieve a single collection - GET /collections/:id.
- Retrieve a curated collection - GET /collections/curated/:id.
- Retrieve a collection’s photos - GET /collections/:id/photos.
- Retrieve a curated collection’s photos - GET /collections/curated/:id/photos.
- Retrieve a list of collections - GET /collections/:id/related.
- Create a new collection - POST /collections.
- Update an existing collection belonging to the logged-in user - PUT /collections/:id.
- Delete a collection belonging to the logged-in user - DELETE /collections/:id.
- Add a photo to one of the logged-in user’s collections - POST /collections/:collection_id/add.
- Remove a photo from one of the logged-in user’s collections - DELETE /collections/:collection_id/remove.
Added support for Current User APIs
- Get the user’s profile - GET /me.
- Update the current user’s profile - PUT /me.
Added support for Stats APIs
- Get a list of counts for all of Unsplash - GET /stats/total.
- Get the overall Unsplash stats for the past 30 days - GET /stats/month.
Major refactorings.

v1.1.0

Documentation updated.
Added support for Authorization.
Added support for Bearer Token.
Added support for private data Read Write Access.
Added support for full Photos APIs
- Get a single page from the list of all photos - GET /photos.
- Get a single page from the list of the curated photos - GET /photos/curated.
- Retrieve a single photo - GET /photos/:id.
- Retrieve a single random photo, given optional filters - GET /photos/random.
- Retrieve statistics of a photo in a specific timeframe - GET /photos/:id/statistics.
- Retrieve a single photo’s download link - GET /photos/:id/download.
- Update a photo on behalf of the logged-in user - PUT /photos/:id.
- Like a photo on behalf of the logged-in user - POST /photos/:id/like.
- Remove a user’s like of a photo - DELETE /photos/:id/like.
Major refactorings.

v1.0.10

Documentation patch.

v1.0.9

Now supports full Search APIs.
Added support for new API endpoints.
- Get a single page of photo results for a query - GET /search/photos.
- Get a single page of collection results for a query - GET /search/collections.
- Get a single page of user results for a query - GET /search/users.

v1.0.8

Now supports full Users APIs.
Added support for new API endpoints.
- Get a list of collections created by the user - GET /users/:username/collections.
- Get a user's account statistics - GET /users/:username/statistics .
Major refactorings.

v1.0.7

Added support for new API endpoint.
- Get a list of photos liked by a user - GET /users/:username/likes.
Minor refactorings.

API Documentation

Schema

Location

The API we are using is https://api.unsplash.com/. Responses are sent as JSON.

Summary objects

When retrieving a list of objects, an abbreviated or summary version of that object is returned - i.e., a subset of its attributes. To get a full detailed version of that object, fetch it individually.

Error messages

If an error occurs, whether on the server or client side, the error message(s) will be returned in an errors array. For example:

422 Unprocessable Entity

{
  "errors": ["Username is missing", "Password cannot be blank"]
}

Authorization

Public Actions

Many actions can be performed without requiring authentication from a specific user. For example, downloading a photo does not require a user to log in. To authenticate requests in this way, pass your application’s access key via the HTTP Authorization header:

Authorization: Client-ID YOUR_ACCESS_KEY

You can also pass this value using a client_id query parameter:

https://api.unsplash.com/photos/?client_id=YOUR_ACCESS_KEY

If only your access key is sent, attempting to perform non-public actions that require user authorization will result in a 401 Unauthorized response.

User Authentication

The Unsplash API uses OAuth2 to authenticate and authorize Unsplash users. Unsplash’s OAuth2 paths live at https://unsplash.com/oauth/.

Before using wrapsplash:

Developers are required to create a developer account from Unsplash.
Create a new App from Your Apps page.
Get the Access Key, Secret key, Callback URLs, and Authorization code.
If you have a Bearer Token, then its super, or else you can generate it using wrapsplash.

Note: Authorization code can be obtained by clicking the Authorize link next to Callback URLs. Also Authorization code is a one-time use code, you have to generate it again, if the action fails!.

Wrapsplash init()

Wrapsplash instance has to be initialized with your credentials obtained from Unsplash developer account for programatic access.These credentials information are passed in to the init() function as options. The following example shows all the available options.

UnsplashApi.init({
    access_key: '<api-key>',
    secret_key: '<secret-key>',
    redirect_uri: '<callback-url>',
    code: '<authorization-code>',
    bearer_token: '<bearer-token>'
});

If you have a bearer_token, then only bearer token has to be passed in.

UnsplashApi.init({
    bearer_token: '<bearer-token>'
});

Generate Bearer Token

A Promise factory to generate a Bearer Token for write_access to private data. The init() method in this case requires access_key, secret_key, redirect_uri, and code to generate bearer token.

Note: No Parameters are required for this function.

const WrapSplash = require('wrapsplash');

let UnsplashApi = new WrapSplash();

UnsplashApi.init({
    access_key: '<api-key>',
    secret_key: '<secret-key>',
    redirect_uri: '<callback-url>',
    code: '<authorization-code>',
});

UnsplashApi.generateBearerToken()
    .then(function (result) {
        console.log(result);
    }).catch(function (e) {
        console.err(e);
    });

If successful, the response body will be a JSON representation of your user’s access token a.k.a bearer token:

{
   "access_token": "091343ce13c8ae780065ecb3b13dc903475dd22cb78a05503c2e0c69c5e98044",
   "token_type": "bearer",
   "scope": "public read_photos write_photos",
   "created_at": 1436544465
 }

and once you have your bearer_token you can use it in your app like this:

UnsplashApi.init({
    bearer_token: '<bearer-token>'
});

Users APIs

Get User's Public Profile

A Promise factory to retrieve public details on a given user.

GET /users/:username

Parameter	Type	Description	Optional
username	string	The username of the particular user	no
width	number	Width of the profile picture in pixels	yes
height	number	Height of the profile picture in pixels	yes

Parameter	Type	Description	Optional	Default
page	number	Page number to retrieve	yes	1
per_page	number	Number of items per page	yes	10
order_by	string	How to sort the photos.(`Valid values: latest, oldest, popular`)	yes	latest

Parameter	Type	Description	Optional
id	string	The photo’s ID	no
width	number	Image width in pixels	yes
height	number	Image height in pixels	yes
rect	string	4 comma-separated integers representing x, y, width, height of the cropped rectangle	yes

Parameter	Type	Description	Optional	Default
collection	String	The public collection ID(‘s) to filter selection. If multiple, comma-separated	yes
featured	Boolean	Limit selection to featured photos	yes	false
username	String	Limit selection to a single user	yes
query	String	Limit selection to photos matching a search term	yes
width	Number	The Image width in pixels	yes
height	Number	The Image height in pixels	yes
orientation	String	Filter search results by photo orientation. (`Valid values are landscape, portrait, and squarish`)	yes	landscape
count	Number	The number of photos to return. (`max: 30`)	yes	1

Parameter	Type	Description	Optional	Default
id	string	The photo’s ID	no
resolution	string	The frequency of the stats	yes	days
quantity	number	The amount of for each stat	yes	30

Parameter	Type	Description	Optional
id	string	The photo’s ID	no
location	object	The location object holding location data	yes
exif	object	The exif object holding exif data	yes

object[key]	Description
location[latitude]	The photo location’s latitude (Optional)
location[longitude]	The photo location’s longitude (Optional)
location[name]	The photo location’s name (Optional)
location[city]	The photo location’s city (Optional)
location[country]	The photo location’s country (Optional)
location[confidential]	The photo location’s confidentiality (Optional)
exif[make]	Camera’s brand (Optional)
exif[model]	Camera’s model (Optional)
exif[exposure_time]	Camera’s exposure time (Optional)
exif[aperture_value]	Camera’s aperture value (Optional)
exif[focal_length]	Camera’s focal length (Optional)
exif[iso_speed_ratings]	Camera’s iso (Optional)

Parameter	Type	Description	Optional	Default
query	string	The search query	no
page	number	Page number to retrieve	yes	1
per_page	number	Number of items per page	yes	10
collections	number	Collection ID(‘s) to narrow search. If multiple, comma-separated.	yes
orientation	string	Filter search results by photo orientation. (`Valid values are landscape, portrait, and squarish.`)	yes	landscape

Parameter	Type	Description	Optional
username	String	The username of the current user	yes
first_name	String	The first name of the current user	yes
last_name	String	The last name of the current user	yes
email	String	The email id of the current user	yes
url	String	The Portfolio/personal URL of the current user	yes
location	String	The location of the current user	yes
bio	String	The About/bio of the current user	yes
instagram_username	String	The Instagram username of the current user	yes

rel	Description
`self`	API location of this collection
`html`	HTML location of this collection
`photos`	API location of this collection’s photos
`related`	API location of this collection’s related collections (Non-curated collections only)
`download`	Download location of this collection’s zip file (Curated collections only)

Parameter	Type	Description	Optional	Default
id	string	The Collection ID	no
page	number	Page number to retrieve	yes	1
per_page	number	Number of items per page	yes	10

Parameter	Type	Description	Optional	Default
title	string	The title of the collection	no
description	string	The collection’s description	yes
private	boolean	Whether to make this collection private	yes	false

Parameter	Type	Description	Optional	Default
collection_id	string	The Collection ID	no
photo_id	string	The Photo ID	no