0.0.977 • Published 1 year ago

droplr-client-ts

Licence

MIT

Version

0.0.977

Deps

Size

322 kB

Vulns

Weekly

Summary Dependency Versions

droplr-client-ts

The TypeScript variant of Droplr's API Client

Installation

$ npm install --save droplr-client-ts

Client
Drops
Boards
Users
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
`AnnotateDrop(data: DataAnnotationProps)`	Drop	Adds an annotation to the drop
`RemoveAnnotation(dropId: string)`	`OK` or `Error`	Deletes the annotation from the Drop
`AddReaction(data: DropReaction)`	DropReaction	Adds an reaction to the drop
`RemoveReaction(reactionId: string)`	`OK` or `Error`	Deletes the reaction from the Drop
`RemoveAllReactions(dropId: string)`	`OK` or `Error`	Deletes all reactions from 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, granularity` StatsConfig
`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;
}

▸ DropAnnotationProps: Interface

interface DropAnnotationProps {
  id?: string;
  dropId: string;
  title: string;
  ctaType: string;
  linkData?: string;
  position: string;
  startTime?: number;
  endTime?: number;
  startTimeText?: string;
  endTimeText?: string;
  shape?: string;
  color?: string;
  fontWeight?: string;
  fontColor?: string;
}

▸ DropReaction: Interface

interface DropReaction {
  id: string;
  dropId: string;
  type: string;
  timestamp: number;
  content: string;
  createdAt: number;
  user?: {
    userId: string;
    guestId: string;
    name: string;
    email: string;
  }
}

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