Telegraph.js

Overview

The Telegra.ph API wrapper made in Typescript. Simplifies creating and managing accounts, pages, and monitor the page stats on Telegraph. It uses schema validation using zod.

Key Features:

• Account Management: Create, edit, and retrieve account info.
• Page Management: Create, edit, and retrieve pages.
• Views: Track page views.

Table of Contents

1. Instalation
2. Usage
   • Client Setup
   • Creating an Account
   • Editing Account Info
   • Get Account Info
   • Revoking Access Token
   • Creating a Page
   • Creating a Page using Markdown
   • Editing a Page
   • Editing a Page using Markdown
   • Retrieving a Page
   • Tracking Page Views
3. API Referenece
   • Constructor
   • Methods
     • createAccount
     • editAccountInfo
     • getAccountInfo
     • revokeAccessToken
     • createPage
     • editPage
     • getPage
     • getPageList
     • getViews

Instalation

npm install telegraph.js

or

yarn add telegraph.js

Usage

Client Setup

Before using any of the API methods, you need to create an instance of the Telegraph class and set the access token.

import { Telegraph } from 'telegraph.js';

const telegraph = new Telegraph();

Creating an Account

const acount = await telegraph.createAccount({
  shortname: 'nugra',
  author_name: 'nugraizy',
  author_url: 'https://github.com/ngraizy',
});

Editing Account Info

const updatedAccount = await telegraph.updateAccount({
  shortname: 'nugra',
  author_name: 'nugraizy',
  author_url: 'https://github.com/ngraizy',
});

Get Account Info

const accountInfo = await telegraph.getAccountInfo({
  fields: ['author_name', 'author_url', 'page_count', 'short_name', 'auth_url'],
});

Revoke Access Token

const account = await telegraph.revokeAccessToken();

Creating a Page

const page = await telegraph.createPage({
  title: 'My first Page',
  author_name: 'nugraizy',
  author_url: 'https://github.com/ngraizy',
  content: [
    {
      tag: 'p',
      children: ['This is a sample page.'],
      tag: 'p',
      attrs: { href: 'https://github.com/nugraizy' },
      children: ['Visit my profile!'],
    },
  ],
  return_content: false,
});

Creating a Page using Markdown

import { Parser } from 'telegraph.js';

const content = Parser.parse(`This is a sample page.

[Visit my profile!](https://github.com/nugraizy)`);

const page = await telegraph.createPage({
  title: 'My first Page',
  author_name: 'nugraizy',
  author_url: 'https://github.com/ngraizy',
  content: content,
  return_content: false,
});

Editing a Page

const updatedPage = await telegraph.editPage({
  author_name: 'nugraizy',
  author_url: 'https://authorurl.com',
  path: 'my-first-page', // usually the path has date in it.
  title: 'Updated Title',
  content: [{ tag: 'p', children: ['Updated content.'] }],
  return_content: false,
});

Editing a Page using Markdown

import { Parser } from 'telegraph.js';

const content = Parser.parse(`Updated content.

[Visit my profile!](https://github.com/nugraizy)`);

const updatedPage = await telegraph.editPage({
  author_name: 'nugraizy',
  author_url: 'https://authorurl.com',
  path: 'my-first-page', // usually the path has date in it.
  title: 'Updated Title',
  content: content,
  return_content: false,
});

Retrieving a Page

const page = await telegraph.getPage({
  path: 'my-first-page', // usually the path has date in it.
  return_content: true,
});

Tracking Page Views

const page = await telegraph.getViews({
  path: 'my-first-page', // usually the path has date in it.
});

API Reference

Constructor

new Telegraph(token?: string);

• token: (optional) — The access token required for making requests to the Telegra.ph API

Methods

createAccount

createAccount({ author_name, short_name, author_url });

Creates a new Telegraph account.

• Parameters:
  • author_name: (string) — The author's name (0-128 characters).
  • short_name: (string) — The account's short name (1-32 characters).
  • author_url: (string) — The author's URL (0-512 characters).
• Returns: Promise<Partial<Account> | undefined>

editAccountInfo

editAccountInfo({ short_name, author_name, author_url });

Edits an existing account.

• Parameters:
  • short_name: (string) — The account's short name.
  • author_name: (string) — The author’s name.
  • author_url: (string) — The author’s URL.
• Returns: Promise<Partial<Omit<Account, 'access_token'>> | undefined>

getAccountInfo

getAccountInfo({ fields });

Retrieves account information.

• Parameters:
  • fields: (string[] | 'short_name', 'author_name', 'author_url', 'auth_url', 'page_count') — List of fields to return (optional).
• Returns: Promise<Partial<Omit<Account, 'access_token'>> | undefined>

revokeAccessToken

revokeAccessToken();

Revoke Current Access Token.

• Returns: Promise<Partial<Account> | undefined>

createPage

createPage({ title, author_name, author_url, content, return_content });

Creates a new page.

• Parameters:
  • title: (string) — The title of the page (1-256 characters).
  • author_name: (string) — The author’s name.
  • author_url: (string) — The author’s URL.
  • content: (NodeElement[]) — The content of the page.
  • return_content: (boolean) — Whether to return the content in the response.
• Returns: Promise<Partial<Page<T>> | undefined>

editPage

editPage({ path, title, content, author_name, author_url, return_content });

Edits an existing page.

• Parameters:
  • path: (string) — The path to the page.
  • title: (string) — The new title.
  • content: (NodeElement[]) — The new content.
  • author_name: (string) — The author’s name.
  • author_url: (string) — The author’s URL.
  • return_content: (boolean) — Whether to return the content in the response.
• Returns: Promise<Partial<Page<T>> | undefined>

getPage

getPage({ path, return_content });

Retrieves a specific page.

• Parameters:
  • path: (string) — The path to the page.
  • return_content: (boolean) — Whether to return the content in the response.
• Returns: Promise<Partial<Page<T>> | undefined>

getPageList

getPageList({ offset, limit });

Retrieves a list of pages.

• Parameters:
  • offset: (number) — Pagination offset (default 0).
  • limit: (number) — Number of pages to retrieve (default 50).
• Returns: Promise<Partial<PageList> | undefined>

getViews

getViews({ path, year, month, day, hour });

Retrieves view statistics for a page.

• Parameters:
  • path: (string) — The path to the page.
  • year: (number) — Year filter (optional).
  • month: (number) — Month filter (optional).
  • day: (number) — Day filter (optional).
  • hour: (number) — Hour filter (optional).
• Returns: Promise<Partial<PageViews> | undefined>