Flickr SDK

The simplest authentication method is providing your API key as a string to createFlickr.

const { flickr } = createFlickr("<your API key>")

OAuth 1.0 allows your application to act on behalf of a user.

1. Obtaining tokens: Initialize createFlickr with oauthToken: false and oauthTokenSecret: false to obtain a request token and authorize a user.
2. Using tokens: Once you have the user's credentials, initialize the client with the full set of keys.

// Step 1: Obtain request token/authorize user
const { upload } = createFlickr({
    consumerKey: "<your API key>",
    consumerSecret: "<your API secret>",
    oauthToken: false,
    oauthTokenSecret: false,
})

// Step 2: Use obtained credentials
const { upload } = createFlickr({
    consumerKey: "<your API key>",
    consumerSecret: "<your API secret>",
    oauthToken: "<the oauth token>",
    oauthTokenSecret: "<the oauth token secret>",
})

To upload photos, you must provide OAuth credentials (consumer key, consumer secret, oauth token, and oauth token secret) to createFlickr. The upload function accepts a file path and an options object.

import { createFlickr } from "flickr-sdk"
import { resolve } from "node:path"

const { upload } = createFlickr({
    consumerKey: "<your API key>",
    consumerSecret: "<your API secret>",
    oauthToken: "<the oauth token>",
    oauthTokenSecret: "<the oauth token secret>",
})

const id = await upload(resolve("example.png"), {
    title: "Works on MY machine!",
})

When writing tests that are expected to fail (i.e., you want to verify that an invalid type relationship correctly triggers a compiler error), use the @ts-expect-error directive. If the code compiles without this directive, TypeScript will flag it as an error because it expected a failure that didn't happen.

import assert from '@flickr/flinch'

// This would normally cause a compilation error
// @ts-expect-error - string is not number
assert.extends<string, number>() // ✅ compiles because we expected the error

Flinch provides two ways to test types: using type-level utilities with assertion functions (like expectTrue) or using the flinch object methods. Both approaches cause TypeScript compilation errors if the type assertion fails.

import flinch, { expectTrue, expectFalse, Equal, Extends } from '@flickr/flinch'

// Using assertion functions (type-level)
expectTrue<Equal<string, string>>() // ✅ compiles
expectFalse<Equal<string, number>>() // ✅ compiles

// Using flinch object methods
flinch.equal<string, string>() // ✅ passes
flinch.extends<'hello', string>() // ✅ passes

// These will cause compilation errors if the condition is not met
// expectTrue<Equal<string, number>>() 
// flinch.equal<string, number>()

In previous versions, the SDK used superagent, where API calls returned a Request object. The current version uses native fetch, so API calls return the response body directly.

// OLD (Superagent)
const res = await flickr.test.login()
console.log(res.body)

// NEW (Fetch)
const body = await flickr('flickr.test.login', {})
console.log(body)

Install the SDK using npm to get access to Flickr API methods and type definitions in Node.js or the browser.

$ npm install flickr-sdk

The oauth.js example demonstrates how to use the OAuth service to obtain an OAuth token and secret to make requests on behalf of a user.

Note: OAuth callback URLs must be https. To run this example, you need an SSL certificate. You can generate a self-signed certificate by running make in the examples directory.

$ make
$ export FLICKR_CONSUMER_KEY=# your application's key
$ export FLICKR_CONSUMER_SECRET=# your application's secret
$ node ./oauth.mjs

To make a standard API call, use createFlickr with your API key. The returned flickr function accepts the method name as a string and an object containing the parameters.

import { createFlickr } from "flickr-sdk"

const { flickr } = createFlickr("<your Flickr API key>")

const res = await flickr("flickr.photos.getInfo", {
    photo_id: '12345',
})

Install the flinch library via npm to perform compile-time TypeScript type testing.

npm install @flickr/flinch

When createFlickr is initialized with OAuth credentials (either via OAuthConfig or OAuthAuth), the returned object includes an additional oauth service. This service is used for OAuth-specific operations.

import { createFlickr } from 'flickr-sdk';

const client = createFlickr({
  consumerKey: '...',
  consumerSecret: '...',
  oauthToken: '...',
  oauthTokenSecret: '...'
});

// The 'oauth' property is available because OAuth credentials were provided
// client.oauth is of type OAuthService
await client.oauth.someOAuthMethod();

The upload.js example demonstrates how to upload a photo on behalf of a user. This requires consumer credentials and a verified OAuth token/secret.

$ export FLICKR_CONSUMER_KEY=# your application's key
$ export FLICKR_CONSUMER_SECRET=# your application's secret
$ export FLICKR_OAUTH_TOKEN=# a verified oauth token
$ export FLICKR_OAUTH_TOKEN_SECRET=# a verified oauth token secret
$ node ./upload.mjs