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 | AnonymousAuth | The Auth method Default: new AnonymousAuth()| | 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 | | GetActivity(id: string, afterId?: string) | Array | Fetches the Drop's activity list | | TriggerTrackingEvent(id: string, type: DropTrackingEvents, options?: DropViewEventProps) | Drop | Fires off a tracking event for the Drop | | 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;
  folder?: string;
  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;
  folder?: string;
}

▸ 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;
}

▸ DropTrackingEvents: enum

enum DropTrackingEvents {
  DOWNLOAD = "DOWNLOAD",
  VIEW = "VIEW",
}

▸ DropViewEventProps: Interface

interface DropViewEventProps {
  referrer?: string;
  displayClass?: string;
  userAgent?: string;
  host?: string;
  password?: string;
}

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));
  });