droplr-client-ts

The TypeScript variant of Droplr's API Client

Installation

$ npm install --save droplr-client-ts

Table of contents

• Client

  • ClientConfig
  • ClientAttributes
  • Example

• Drops

  • DropsMethods
  • DropsInterfaces
  • Examples

• Boards

  • BoardsMethods
  • BoardsInterfaces
  • Examples

• Users

  • UsersMethods
  • UsersInterfaces
  • Examples

• Teams

  • TeamsMethods
  • Examples

• RequestConfig

  • Examples

• Errors

  • Examples

API

Client

▸ Client(ClientConfig): Class

The primary access point for the API Client.

Constructor

▸ ClientConfig: Interface

new Client(config as ClientConfig)

ClientConfig Props

Name	Type	Description
baseUrl	string	The URL the requests are sent to Default: https://api.droplr.com
auth	JwtAuth	BasicAuth
onResponse	Function	The callback for successful requests
onError	Function	The callback for requests gone wrong

Attributes

Name	Type	Description
Drops	Drops	The Drops accessor
Boards	Boards	The Boards accessor
Users	Users	The Users accessor
Teams	Teams	The Teams accessor

Example

// JWTAuth
const API = new Client({
  baseUrl: "https://api.droplr.com",
  auth: new JwtAuth(TOKEN),
  onError: (e) => console.log(e) 
} as ClientConfig);

// BasicAuth
API = new Client({
  baseUrl: "https://api.droplr.com",
  auth: new BasicAuth(USERNAME, PASSWORD),
  onError: (e) => console.log(e) 
} as ClientConfig);

API.Users.Current().then(...)

Drops

▸ Drops: Class

Provides access to the endpoints related to a user's Drops

Methods

Call	Returns	Description
Get(id: string, params?: GetDropsOptions)	Drop	Returns a Drop object with the matching ID Optional Can take {drop_password, content_disposition} as additional GetDropsOptions parameter
GetLastTen()	Array	Returns the last 10 drops the user made
GetMultiple(options: GetMultipleDropsOptions)	DropsList	Returns multiple drops queried with additional parameters GetMultipleDropsOptions
GetSharedDrops(options: GetSharedDropsOptions)	DropsList	Returns multiple shared drops queried with additional parameters GetSharedDropsOptions
GetAllDropsInBoard(boardId: string, boardPassword?: string)	Array	Returns all the drops in the specified board Optional Takes boardPassword as a parameter if the board is private
Create(data: CreateDropMetadata)	Drop	Creates a new Drop and returns it. Optionally, pass a onProgressUpdated(percentage, uploadedBytes, isCompleted) callback to track upload progress (from Chromium 105 and after).CreateDropMetadata
Update(id: string, dropData: Drop)	Drop	Updates the drop's properties
DuplicateDrop(id: string)	Drop	Creates a duplicate of the Drop
ListHits(id: string)	DropsList	Returns the views on the Drop DropsList
GetStats(options: StatsConfig)	Object	Returns the basic Drop stats, lastAccess, start, end, granularityStatsConfig
GetReferrers(id: string)	Array	Fetches the Drop's referrers
Delete(id: string)	OK or Error	Deletes the Drop
DeleteMultiple(ids: Array<string>)	OK or Error	Deletes the Drops provided

Interfaces

▸ CreateDropMetadata: Interface

interface CreateDropMetadata {
  title: string;
  type: "FILE" | "LINK" | "NOTE" | "FOLDER";
  variant: string; // ie. image/png
  content: any; // Blob
  board?: string;
  pixelDensity?: number;
  onProgressUpdated?: (
    progress: number,
    uploaded: number,
    completed: boolean
  ) => void;
}

▸ DropsList: Interface

interface DropsList {
  count: number;
  hasMore: boolean;
  results: Array<HitData>;
}

▸ GetDropFilters: Interface

interface GetDropFilters {
  /** Drop Type, ie. FILE/VIDEO/IMAGE */
  type?: string;
  /** Drop Variant, ie. image/png */
  variant?: string;
  /** Title-based search */
  search?: string;
  /** Filter since timestamp, ie. 1705483733454 */
  since?: string;
  /** Filter until timestamp, ie. 1705483733454 */
  until?: string;
  /** Ordering, ASC/DESC */
  order?: "ASC" | "DESC";
  /** Sort by, ie. TITLE/CREATED_AT/VIEWS/SIZE/ACTIVITY */
  sort?: "TITLE" | "CREATED_AT" | "VIEWS" | "SIZE" | "ACTIVITY" | "VIEWS";
  /** Filters drops containing the provided tags */
  tags: string[];
  /** Filters drops based on starred property */
  favorite?: boolean;
}

▸ GetMultipleDropsOptions: Interface

interface GetMultipleDropsOptions {
  owner?: string;
  amount?: number;
  board?: string;
  offset?: number;
  filter?: 
}

▸ GetSharedDropsOptions: Interface

interface GetMultipleDropsOptions {
  amount?: number;
  offset?: number;
}

▸ HitData: Interface

interface HitData {
  id: string;
  code: string;
  owner: string;
  userAgent: string;
  timestamp: number;
}

▸ StatsConfig: Interface

interface StatsConfig {
  id: string;
  slice:
    | "HOURLY_LAST_24H"
    | "HOURLY_LAST_TWO_DAYS"
    | "DAILY_LAST_WEEK"
    | "DAILY_LAST_TWO_WEEKS"
    | "DAILY_LAST_MONTH"
    | "DAILY_LAST_TWO_MONTHS"
    | "WEEKLY_LAST_SIX_MONTHS";
  format?: "DATETIME" | "DEFAULT";
  timezoneOffset?: number;
}

Examples

// Initialize the Client
const API = new Client({
  baseUrl: "https://api.droplr.com",
  auth: new JwtAuth(TOKEN),
  onError: (e) => console.log(e) 
} as ClientConfig);

// Fetch a Drop
API.Drops.Get('TEST_ID').then(
    (res) => {
        res.json().then(
            (drop: Drop) => {
                handleDrop(drop)
            }
        )
    }
)

// Create a new Drop
API.Drops.Create({
        title: "MyImage",
        type: "FILE",
        variant: "image/png",
        content: imageBlob,
      }).then(
    (res) => {
        res.json().then(
            (drop: Drop) => {
                handleDrop(drop)
            }
        )
    }
)


// Create a new Drop and track its progress
API.Drops.Create({
        title: "MyImage",
        type: "FILE",
        variant: "image/png",
        content: imageBlob,
        onProgressUpdated(progress, uploaded, completed) {
        console.log(`Current progress: ${progress}%, total uploaded bytes: ${uploaded}`);
        if(completed) {
            handleUploadComplete();
            }
        }
      }).then(
    (res) => {
        res.json().then(
            (drop: Drop) => {
                handleDrop(drop)
            }
        )
    }
)

** IMPORTANT **
Since the StreamAPI is a relatively new feature, feature detection using the below snippet is advised: 

const supportsRequestStreams = (() => {
  let duplexAccessed = false;

  const hasContentType = new Request('', {
    body: new ReadableStream(),
    method: 'POST',
    get duplex() {
      duplexAccessed = true;
      return 'half';
    },
  }).headers.has('Content-Type');

  return duplexAccessed && !hasContentType;
})();

if (supportsRequestStreams) {
  // …
} else {
  // …
}

// Update a Drop
API.Drops.Update("TEST_ID", {
        title: "RenamedImage",
        privacy: "TEAM"
    });

Boards

▸ Boards: Class

Provides access to the endpoints related to a user's Boards

Methods

Call	Returns	Description
Get(id: string)	Board	Returns the Board specified by the ID
GetAll()	Array	Fetches all of the user's Boards
GetSharedWithTeam()	Array	Fetches all of the Boards the user has shared with his team
Create(data: CreateBoardData)	Board	Creates a new Board CreateBoardData
Update(id: string, data: UpdateBoardData)	Board	Updates a Board UpdateBoardData
Watch(id: string, password?: string)	OK or Error	Sets a Board to be watched
StopWatching(id: string, password?: string)	OK or Error	Stops watching a Board
Delete(id: string)	OK or Error	Deletes a Board

Interfaces

▸ CreateBoardData: Interface

interface CreateBoardData {
  name: string;
  privacy?: "PRIVATE" | "PUBLIC";
  uploadPrivacy?: "PRIVATE" | "PUBLIC";
  password?: string;
  isPublic?: boolean;
  groupsAccessList?: [];
  accessList?: [];
}

▸ UpdateBoardData: Interface

interface UpdateBoardData {
  name?: string;
  privacy?: "PRIVATE" | "PUBLIC";
  uploadPrivacy?: "PRIVATE" | "PUBLIC";
  password?: string;
  isPublic?: boolean;
  groupsAccessList?: [];
  accessList?: [];
  poweredBy?: boolean;
}

Examples

// Initialize the Client
const API = new Client({
  baseUrl: "https://api.droplr.com",
  auth: new JwtAuth(TOKEN),
  onError: (e) => console.log(e) 
} as ClientConfig);

// Fetch a Board
API.Boards.Get('TEST_ID').then(
    (res) => {
        res.json().then(
            (board: Board) => {
                handleBoard(board)
            }
        )
    }
)

// Create a new Board
API.Boards.Create({ 
    name: "NewBoard", 
    password: "Secret", 
    privacy: "PRIVATE" 
    }).then(
        (res) => {
            res.json().then(
                (board: Board) => {
                    handleBoard(board)
                }
            )
        }
)

// Update a Board
API.Boards.Update("TEST_ID", {
        name: "RenamedBoard",
        privacy: "PUBLIC", 
        password: ""
    });

Users

▸ Users: Class

Provides access to the endpoints related to the User who's token initialized the Client

Methods

Call	Returns	Description
Current()	User	Returns the User who's token initialized the Client
Create(data: CreateUserData)	User	Creates a new User CreateUserData
Update(id: string, data: UpdateUserData)	User	Updates a User UpdateUserData
Delete(id: string)	OK or Error	Deletes a User
Tags(id: string)	Array	Fetches a Users Tags
Boards(id: string)	Array	Fetches a Users Boards

Interfaces

▸ CreateUserData: Interface

interface CreateUserData {
    email: string;
    password: string;
}

▸ UpdateUserData: Interface

interface UpdateUserData {
    email?: string;
    username?: string;
    dropPrivacy?: "PUBLIC" | "PRIVATE" | "TEAM";
    theme?: "STANDARD" | "DARK" | "LIGHT";
}

Examples

// Initialize the Client
const API = new Client({
  baseUrl: "https://api.droplr.com",
  auth: new JwtAuth(TOKEN),
  onError: (e) => console.log(e) 
} as ClientConfig);

// Fetch the current user
API.Users.Current.then(
    (res) => {
        res.json().then(
            (user: User) => {
                handleBoard(user.id)
            }
        )
    }
)

// Update a User
API.Users.Update("TEST_ID", {
    theme: "DARK"
});

// Fetch a User's Boards
API.Users.Boards().then(
    (res) => {
        res.json().then(
            (boards: Array<Board>) => {
                boards.forEach(
                    b => handleBoard(b)
                )
            }
        )
    }
)

Teams

▸ Teams: Class

Provides access to the endpoints related to the user's Teams

Methods

Call	Returns	Description
Get(id: string)	Team	Returns the specified Team
GetAccountsInTeam(id: string)	Array	Fetches a list of Users in a specific Team
Update(id: string, data: UpdateTeamData)	Team	Updates the specified Team

Interfaces

▸ UpdateTeamData: Interface

interface UpdateTeamData {
  billing?: "NONE" | "MONTHLY" | "ANNUAL" | "LIFETIME",
  payment_type?: "NONE" | "CREDIT_CARD" | "INVOICE_CREDIT_CARD" | "INVOICE_PO" | "APPSUMO" | "STACK_SOCIAL",
  selfDestructType?: "NONE" | "VIEWS" | "TIME",
  selfDestructValue?: number,
  selfDestructReminderType?: "NONE" | "VIEWS" | "TIME",
  selfDestructReminderValue?: number,
  name?: string,
  dropPrivacy?: "PUBLIC" | "PRIVATE" | "TEAM" | "OBSCURE",
  theme?: "STANDARD" | "DARK" | "LIGHT",
  domainType?: "DEFAULT" | "SUB_DOMAIN" | "DOMAIN",
  domain?: string,
  rootRedirect?: string,
  useRootRedirect?: boolean,
  subdomain?: string,
  useLogo?: boolean,
  visionRedaction?: "ON" | "OFF",
  useUserSettings?: boolean,
  useUserSelfDestructSettings?: boolean,
  useUserPrivacySettings?: boolean,
  sslEnabledOnCustomDomain?: boolean,
  poweredBy?: boolean,
  useEmailDomain?: boolean,
  invitePrivilege?: "ALL" | "ADMIN_ONLY",
  storageProvider?: "AMAZON" | "AZURE" | "GOOGLE_DRIVE" | "AMAZON_S3" | "DROPBOX",
  useUserStorageProvider?: boolean,
  redaction?: "ALL" | "TEAM" | "NONE",
  useUserRedaction?: boolean,
  excludeRedactionGroupsList?: any,
}

interface TeamSettings {
  domainType: string;
  logo: string;
  name: string;
  rootRedirect: string;
  subdomain: string;
  theme: "STANDARD" | "DARK" | "LIGHT";
  useLogo: boolean;
  useRootRedirect: boolean;
  type: "FREE" | "PRO" | "ENTERPRISE";
}

Examples

// Initialize the Client
const API = new Client({
  baseUrl: "https://api.droplr.com",
  auth: new JwtAuth(TOKEN),
  onError: (e) => console.log(e) 
} as ClientConfig);

// Fetch a Teams data
API.Teams.Get("TEST_ID").then(
    (res) => {
        res.json().then(
            (team: Team) => {
                handleTeam(team.settings.name)
            }
        )
    }
)

// Fetch the Users in a Team
API.Teams.GetAccountsInTeam("TEST_ID").then(
    (res) => {
        res.json().then(
            (users: Array<User>) => {
                users.forEach(
                    u => removeUser(u.id)
                )
            }
        )
    }
);

Additional request configuration

Some request support additional fetch() configuration

Interfaces

▸ ClientError: Interface

interface OptionalRequestConfig {
  abortSignal?: AbortSignal;
}

Examples

/** Prematurely aborting a request */
const abortController = new AbortController();
const abortSignal = abortController.signal;

API.Drops.Create(
    {
        title: "TestImg2",
        type: "FILE",
        variant: "image.png",
        content: b,
    },
    { signal: abortSignal }
    )
    .then((_response) => {});

setTimeout( () => abortController.abort(), 50);

Errors

Errors are thrown and contain both the HTTP response and the error object.

Interfaces

▸ ClientError: Interface

interface ClientError {
    code: number;
    statusCode: number;
    message: string;
    response: Response;
    errors: any[];

}

Examples

API.Teams.GetAccountsInTeam("TEST_ID")
  .then((res) => {
    res.json().then((team) => {
      console.log(team);
    });
  })
  .catch((e: ClientError) => {
    console.log(e.code, e.message);
    e.response.json().then((r) => console.log(r));
  });