note-blog-kit 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ludy-kida
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,341 @@
1
- # Temporary Holding Version
1
+ # note-blog-kit
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 自分の note 記事を、React + TypeScript のサイトに数十行でブログとして載せるためのライブラリ(開発中・仮称)。
4
+
5
+ ## 注意事項
6
+
7
+ - note の**非公式 API** を利用しており、予告なく動かなくなる可能性があります
8
+ - note 株式会社とは無関係のライブラリです
9
+ - **自分の記事**を表示する用途を想定しています(他人の記事の転載はしないでください)
10
+ - キャッシュを有効にし、高頻度なアクセスはしないでください
11
+ - canonical は note の元 URL を推奨します
12
+ - 有料部分は表示しません
13
+
14
+ ## 導入手順(Next.js App Router)
15
+
16
+ ### 1. インストール
17
+
18
+ ```bash
19
+ npm install note-blog-kit
20
+ ```
21
+
22
+ React のコンポーネント(`note-blog-kit/react`)を使う場合は React 18 / 19 が必要です。取得(`note-blog-kit/server`)は Node.js 22.12 以上で動きます。
23
+
24
+ ### 2. デフォルト CSS を読み込む(任意)
25
+
26
+ ```tsx
27
+ // app/layout.tsx
28
+ import 'note-blog-kit/styles.css';
29
+ ```
30
+
31
+ ### 3. 一覧ページを作る
32
+
33
+ ```tsx
34
+ // app/blog/page.tsx
35
+ import { unstable_cache } from 'next/cache';
36
+ import { notFound } from 'next/navigation';
37
+ import { NoteArticleList, NotePagination } from 'note-blog-kit/react';
38
+ import { listArticles } from 'note-blog-kit/server';
39
+
40
+ // 取得結果を1時間キャッシュする(キャッシュに当たれば note へのリクエストも、ライブラリの間隔待ちも起きない)。
41
+ // ユーザー名は引数にしてキャッシュのキーに含める(変えたときに前のユーザーの記事が出ないように)
42
+ const getPage = unstable_cache(
43
+ (user: string, page: number) => listArticles({ user, page }),
44
+ ['note-articles'],
45
+ { revalidate: 3600 },
46
+ );
47
+
48
+ type Props = { searchParams: Promise<{ page?: string }> };
49
+
50
+ export default async function BlogPage({ searchParams }: Props) {
51
+ const page = Number((await searchParams).page ?? '1');
52
+ if (!Number.isInteger(page) || page < 1 || page > 100) notFound();
53
+ const { articles, isLastPage, totalCount } = await getPage('your_urlname', page);
54
+ if (articles.length === 0 && page > 1) notFound();
55
+ return (
56
+ <main>
57
+ <h1>ブログ</h1>
58
+ <NoteArticleList articles={articles} />
59
+ <NotePagination page={page} isLastPage={isLastPage} totalCount={totalCount} getHref={(p) => `/blog?page=${p}`} />
60
+ </main>
61
+ );
62
+ }
63
+ ```
64
+
65
+ 記事のリンク先は、既定では note の記事ページです。自分のサイトの詳細ページにしたい場合は `getHref` と `linkComponent={Link}` を渡します(下の「4. 詳細ページを作る」)。
66
+
67
+ ### 4. 詳細ページを作る(任意)
68
+
69
+ `app/articles/[key]/page.tsx` を作ります。`note-blog-kit/next` のヘルパーで、静的生成するキーと metadata を作れます。
70
+
71
+ ```tsx
72
+ import { generateNoteMetadata, generateNoteStaticParams } from 'note-blog-kit/next';
73
+ import { NoteArticleBody } from 'note-blog-kit/react';
74
+ import { getArticle, isNoteError } from 'note-blog-kit/server';
75
+ import { notFound } from 'next/navigation';
76
+
77
+ const USER = 'your_urlname';
78
+ type Props = { params: Promise<{ key: string }> };
79
+
80
+ async function findArticle(key: string) {
81
+ const article = await getArticle({ key }).catch((error: unknown) => {
82
+ // 不正なキー・見つからない記事だけ 404 にする(タイムアウトなどは 404 にしない)
83
+ if (error instanceof TypeError || (isNoteError(error) && error.code === 'NOTE_NOT_FOUND')) return null;
84
+ throw error;
85
+ });
86
+ // getArticle は誰の記事でも返すので、自分の記事か確かめる
87
+ if (article === null || article.author.urlname !== USER) notFound();
88
+ return article;
89
+ }
90
+
91
+ // ビルド時に新しい記事から 20 ページ分(120件)を生成する(maxPages で変更できる)
92
+ export const generateStaticParams = () => generateNoteStaticParams({ user: USER });
93
+
94
+ export async function generateMetadata({ params }: Props) {
95
+ // canonical は既定で note の元 URL。自分のサイトを正にするなら { canonical: '...' } を渡す
96
+ return generateNoteMetadata(await findArticle((await params).key));
97
+ }
98
+
99
+ export default async function ArticlePage({ params }: Props) {
100
+ const article = await findArticle((await params).key);
101
+ return (
102
+ <main>
103
+ <h1>{article.title}</h1>
104
+ <NoteArticleBody article={article} />
105
+ </main>
106
+ );
107
+ }
108
+ ```
109
+
110
+ - **キャッシュ**:`generateMetadata` とページで同じ記事を取得するので、`unstable_cache` などで結果をキャッシュしてください([`examples/next`](https://github.com/ludy-kida/note-blog-kit/tree/main/examples/next) の詳細ページを参照)
111
+ - **URL のキーは外部から自由に指定されます**:上の例のままだと、形式が正しいキーなら自分の記事でなくても note に問い合わせます。公開するサイトでは、自分の記事のキーの一覧(`generateNoteStaticParams` の結果をキャッシュしたもの)にあるときだけ `getArticle` を呼んでください(`examples/next` はそうしています)
112
+ - **`generateNoteStaticParams`**:`listAllArticles` で記事を集めます。`maxPages`(既定 20 ページ)を超える古い記事はビルド時には生成しませんが、`dynamicParams` を既定の true のままにしておけば最初のアクセス時に表示できます。`param` で動的セグメントの名前(既定 `'key'`)を変えられます
113
+ - **`generateNoteMetadata`**:`title`・`description`(抜粋)・`alternates.canonical`・Open Graph・Twitter カードを返します。Next.js の `Metadata` にそのまま代入できます(`note-blog-kit` は `next` に依存しません)。`formatTitle` でタイトルを加工できます
114
+
115
+ ### キャッシュの推奨
116
+
117
+ - `listArticles` は呼ぶたびに note へリクエストします。**呼び出しの結果ごとキャッシュしてください**(Next.js なら上の例の `unstable_cache`、ほかの環境ではビルド時に JSON へ書き出すなど)
118
+ - 同じプロセス内の連続リクエストは、ライブラリが自動で1秒以上空けます。この待ちは `listArticles` を呼ぶたびに入るため、`fetch` 単位のキャッシュ(`next: { revalidate }`)だけでは、同時アクセスが多いとページの表示が遅れます
119
+ - **ページ番号に上限を設けてください**(上の例では100)。上限がないと、`?page=` を変えたアクセスでキャッシュに無いページを取りに行かせ続けられます
120
+ - 全件の取得(`listAllArticles`)は1ページ6件ずつ取りに行くため時間がかかります。ビルド時やキャッシュの更新時に行ってください
121
+
122
+ 動く例は [`examples/next`](https://github.com/ludy-kida/note-blog-kit/tree/main/examples/next) にあります。
123
+
124
+ ## 使い方(開発中・API は 0.x の間に変わることがあります)
125
+
126
+ ### 記事一覧を取得する(サーバー側)
127
+
128
+ note は CORS に対応していないため、取得はサーバー側(Next.js の Server Component・Route Handler、ビルド時のスクリプトなど)で行います。
129
+
130
+ ```ts
131
+ import { isNoteError, listArticles } from 'note-blog-kit/server';
132
+
133
+ try {
134
+ const { articles, isLastPage, totalCount } = await listArticles({ user: 'your_urlname', page: 1 });
135
+ } catch (error) {
136
+ if (isNoteError(error) && error.code === 'NOTE_NOT_FOUND') {
137
+ // ユーザーが見つからない
138
+ }
139
+ throw error;
140
+ }
141
+ ```
142
+
143
+ | オプション | 既定値 | 説明 |
144
+ | --- | --- | --- |
145
+ | `user` | (必須) | note のユーザー名(英数字・`_`・`-`) |
146
+ | `page` | `1` | ページ番号。1ページは6件 |
147
+ | `timeoutMs` | `10000` | タイムアウト(ミリ秒) |
148
+ | `minIntervalMs` | `1000` | 連続リクエストの最小間隔(ミリ秒)。プロセス全体で1本の列にまとめて送ります |
149
+ | `signal` | — | 中断用の `AbortSignal` |
150
+ | `fetch` | `globalThis.fetch` | fetch の差し替え(テスト・キャッシュ層用)。Cookie・認証ヘッダーは付けないでください |
151
+
152
+ エラーは `code` で判別します:`NOTE_NOT_FOUND`(404)、`NOTE_HTTP_ERROR`(その他の HTTP エラー、`status` あり)、`NOTE_NETWORK_ERROR`、`NOTE_TIMEOUT`、`NOTE_SCHEMA_ERROR`(note のレスポンスの形が変わった)。
153
+
154
+ 結果は必ずキャッシュし、高頻度に呼び出さないでください(方法は上の「キャッシュの推奨」を参照)。
155
+
156
+ ### 全件を取得する(ビルド時向け)
157
+
158
+ 1ページは6件固定のため、全件の取得には多くのリクエストが必要です(237件なら約40回、1秒間隔で約40秒)。全件取得はビルド時やキャッシュの更新時に行ってください。既定では **20ページ(120件)で打ち切ります**。
159
+
160
+ ```ts
161
+ import { iterateArticles, listAllArticles } from 'note-blog-kit/server';
162
+
163
+ // 配列でまとめて取得する
164
+ const { articles, truncated } = await listAllArticles({ user: 'your_urlname', maxPages: 50 });
165
+ if (truncated) {
166
+ // maxPages に達して打ち切った(続きがある)
167
+ }
168
+
169
+ // 1件ずつ処理する
170
+ for await (const article of iterateArticles({ user: 'your_urlname' })) {
171
+ console.log(article.title);
172
+ }
173
+ ```
174
+
175
+ `maxPages`(既定 `20`)以外のオプションは `listArticles` と同じです(`page` は指定できません)。取得中に新しい記事が公開されてページがずれた場合も、同じ記事は1回だけ返します。
176
+
177
+ - `truncated: true` は `maxPages` に達して打ち切ったことを表します(続きがある可能性があります)
178
+ - `listAllArticles` は途中のページで失敗すると、それまでに集めた記事を返さずにエラーを投げます。途中までの記事も使いたい場合は `iterateArticles` を使ってください
179
+ - `for await` では打ち切りの有無を受け取れません。必要なら `listAllArticles` を使うか、`next()` を手で回して戻り値(`done: true` のときの `value`)を読んでください
180
+
181
+ ### 記事1件を取得する(サーバー側)
182
+
183
+ ```ts
184
+ import { getArticle } from 'note-blog-kit/server';
185
+
186
+ const article = await getArticle({ key: 'n55256baa5425' }); // 記事 URL の /n/ の後ろ
187
+
188
+ // note の API は記事キーだけで誰の記事でも返します。他人の記事を表示しないよう、著者を確かめてください
189
+ if (article.author.urlname !== 'your_urlname') {
190
+ // 404 として扱う
191
+ }
192
+
193
+ article.bodyHtml; // サニタイズ済みの本文 HTML(サニタイズは外せません)
194
+ article.isPartial; // 有料記事で本文が途中までのとき true(「続きは note で」を出す)
195
+ article.toc; // 目次(id は本文の見出しの id と同じ。有料記事では有料部分の見出しも含む)
196
+ article.embeds; // 本文中の埋め込み(本文の <figure data-nbk-embed-key> と key で対応)
197
+ ```
198
+
199
+ `key` は `n` と英小文字・数字だけを受け付け、それ以外は送信せずに `TypeError` を投げます(ページの URL から受け取った値なら 404 として扱ってください)。オプション(`fetch`・`signal`・`timeoutMs`・`minIntervalMs`)とエラーは `listArticles` と同じです。結果は必ずキャッシュしてください。
200
+
201
+ ### 一覧を表示する(React)
202
+
203
+ `note-blog-kit/react` のコンポーネントは、取得済みのデータを受け取って描画するだけです。見た目は持たず、`nbk-` から始まるクラス名を付けます。フックを使わないため、Server Component としても使えます(React 18 / 19)。
204
+
205
+ ```tsx
206
+ import Link from 'next/link';
207
+ import { NoteArticleList, NotePagination } from 'note-blog-kit/react';
208
+ import { listArticles } from 'note-blog-kit/server';
209
+
210
+ export default async function BlogPage() {
211
+ const { articles, page, isLastPage, totalCount } = await listArticles({ user: 'your_urlname' });
212
+ return (
213
+ <>
214
+ <NoteArticleList articles={articles} linkComponent={Link} getHref={(article) => `/blog/${article.key}`} />
215
+ <NotePagination page={page} isLastPage={isLastPage} totalCount={totalCount} getHref={(p) => `/blog?page=${p}`} />
216
+ </>
217
+ );
218
+ }
219
+ ```
220
+
221
+ | コンポーネント | 主な props と既定値 |
222
+ | --- | --- |
223
+ | `NoteArticleList` | `articles`(必須)、`getHref`(既定は note の記事 URL)、`linkComponent`(既定 `'a'`)、`formatDate`(既定は日本時間の `YYYY/MM/DD`)、`headingLevel`(既定 `2`)、`renderItem`(各記事の描画を差し替え)、`empty`(既定「記事がありません」) |
224
+ | `NoteArticleCard` | `article`(必須)、`href`(既定は note の記事 URL)、`linkComponent`、`formatDate`、`headingLevel`、`labels.paid`(既定「有料」) |
225
+ | `NotePagination` | `page`・`isLastPage`・`getHref`(必須)、`totalCount`(あれば「3 / 40」と表示)、`perPage`(既定 `6`)、`linkComponent`、`labels`(既定「前へ」「次へ」、aria-label「ページ送り」) |
226
+
227
+ - **クラス名**:`nbk-card`(`__eyecatch`・`__title`・`__link`・`__date`・`__badge`・`__excerpt`・`__tags`・`__tag`)、`nbk-article-list`(`__item`、0件のときは `--empty` と `__empty`)、`nbk-pagination`(`__prev`・`__next`・`__status`)。`className` を渡すと、既定のクラス名に追加されます
228
+ - **リンク先に信頼できない値を渡さない**:`href`・`getHref` の値はそのまま `href` 属性に入ります。React 18 は `javascript:` の URL をブロックしません。既定値(note の記事 URL)は、http(s) でなければリンクにしません
229
+ - **Next.js の typedRoutes**:有効にしている場合は `Link` の `href` が文字列を受け付けないため、`Link` を包んだコンポーネントを `linkComponent` に渡してください
230
+ - **見出し画像**:note の CDN(assets.st-note.com)から直接読み込みます
231
+
232
+ ### 本文を表示する(React)
233
+
234
+ `NoteArticleBody` は `getArticle` で取得した記事の本文を描画します。`dangerouslySetInnerHTML` は使わず、サニタイズ済みの本文を、許可したタグ・属性だけの React 要素にします。有料記事(`isPartial`)では、本文の後に「続きは note で」リンクを出します。
235
+
236
+ ```tsx
237
+ import { getArticle } from 'note-blog-kit/server';
238
+ import { NoteArticleBody } from 'note-blog-kit/react';
239
+
240
+ export default async function Page({ params }: { params: Promise<{ key: string }> }) {
241
+ const article = await getArticle({ key: (await params).key });
242
+ return (
243
+ <article>
244
+ <h1>{article.title}</h1>
245
+ <NoteArticleBody
246
+ article={article}
247
+ components={{
248
+ // 画像・見出し・埋め込み・目次を任意のコンポーネントに置き換えられる
249
+ img: ({ src, alt, width, height }) => <img src={src} alt={alt} width={width} height={height} />,
250
+ }}
251
+ labels={{ readMore: '続きを note で読む' }}
252
+ />
253
+ </article>
254
+ );
255
+ }
256
+ ```
257
+
258
+ | props | 内容 |
259
+ | --- | --- |
260
+ | `article`(必須) | `getArticle` の戻り値 |
261
+ | `components` | `img`(`src`・`alt`・`width`・`height`)、`heading`(`level`: 2〜4・`id`・`children`)、`embed`(`embed`: `NoteEmbed \| null`・`service`・`children`)、`toc`(`items`)を置き換える |
262
+ | `readMoreHref` | 「続きは note で」のリンク先。既定は記事 URL(http(s) でなければ出さない) |
263
+ | `linkComponent` | 「続きは note で」と note の埋め込みのリンクに使う要素。既定は `'a'` |
264
+ | `labels` | `readMore`(既定「続きは note で」)、`toc`(既定「目次」) |
265
+
266
+ - **既定の描画**:外部記事の埋め込みは中のリンクカード、note の埋め込みは記事へのリンクを出します(`iframe` は出しません)。目次の位置には `article.toc` を出し、本文にない見出し(有料部分)はリンクにしません
267
+ - **クラス名**:
268
+ - `nbk-body`(`__more`・`__more-link`)
269
+ - 本文の要素:`nbk-body__p`・`__h2`・`__h3`・`__h4`・`__a`・`__ul`・`__ol`・`__blockquote`・`__figure`・`__figcaption`・`__img`・`__pre`・`__code`・`__hr`・`__table`・`__th`・`__td`。`li`・`strong`・`em` などにはクラスを付けません。`components` で置き換えた画像・見出しにも付きません
270
+ - `nbk-toc`(`__title`・`__list`・`__item`・`__item--h2`/`--h3`・`__link`)
271
+ - `nbk-embed`(`data-service` 属性)。埋め込みの中のリンクは `nbk-body__a` ではなく `nbk-embed__link` になります
272
+ - **他人の記事**:`getArticle` は誰の記事でも返します。URL から受け取ったキーで表示する場合は、`article.author.urlname` を確かめてください
273
+
274
+ ### デフォルト CSS(任意)
275
+
276
+ note の見た目に合わせた CSS を用意しています。読み込まなければ、コンポーネントは見た目を持ちません。
277
+
278
+ ```ts
279
+ // Next.js(App Router)なら app/layout.tsx、Pages Router なら pages/_app.tsx、Vite なら main.tsx などで読み込む
280
+ import 'note-blog-kit/styles.css';
281
+ ```
282
+
283
+ CSS は `:root`(変数の既定値)と `nbk-` から始まるクラスにだけ当たり、サイトの他の要素には影響しません。色や余白は CSS 変数で変えられます。
284
+
285
+ | 変数 | 既定値 | 用途 |
286
+ | --- | --- | --- |
287
+ | `--nbk-font-family` | Hiragino Sans など | 文字(サイトのフォントを使うなら `inherit`) |
288
+ | `--nbk-color-text` | `#08131a` | タイトルなど |
289
+ | `--nbk-color-muted` | `#6e7b85` | 日付・抜粋・タグ・件数 |
290
+ | `--nbk-color-accent` | `#41c9b4` | ホバー・フォーカス |
291
+ | `--nbk-color-border` | `#e6e6e6` | 枠線 |
292
+ | `--nbk-color-placeholder` | `#f2f2f2` | 見出し画像の読み込み中の下地 |
293
+ | `--nbk-color-surface` | `transparent` | カードの背景(既定はページの背景のまま) |
294
+ | `--nbk-color-badge-bg` / `--nbk-color-badge-text` | `#08131a` / `#fff` | 「有料」バッジ |
295
+ | `--nbk-radius` | `8px` | 角丸 |
296
+ | `--nbk-list-gap` | `24px` | 一覧のカードの間隔、ページ送りの上下の余白 |
297
+ | `--nbk-card-min-width` | `280px` | 一覧で1枚のカードが取る最小幅 |
298
+ | `--nbk-body-max-width` | `620px` | 本文の最大幅 |
299
+ | `--nbk-body-font-size` / `--nbk-body-line-height` | `18px` / `2` | 本文の文字サイズ・行間(note に合わせた値) |
300
+ | `--nbk-body-gap` | `1.5em` | 本文の段落などの間隔 |
301
+ | `--nbk-color-subtle` | `#f5f8fa` | コードブロック・目次の背景 |
302
+ | `--nbk-color-button-bg` / `--nbk-color-button-text` | `#08131a` / `#fff` | 「続きは note で」ボタン |
303
+
304
+ #### 優先順位(カスケードレイヤー)
305
+
306
+ すべてのルールは `@layer note-blog-kit` の中にあります。
307
+
308
+ - **レイヤーに入っていないあなたの CSS** は、詳細度に関係なく note-blog-kit より優先されます。サイト全体の要素スタイル(例:`a { text-decoration: underline }`、`h2 { margin: ... }`)もカードに効くので、必要ならクラス名で打ち消してください
309
+ - **あなたがレイヤーを使っている場合**(Tailwind CSS v4 など)は、レイヤーの順序は最初に宣言された順で決まります。読み込む順番に頼らず、順序を宣言してください。Tailwind v4 なら、リセット(`base`)より後・ユーティリティ(`utilities`)より前に置くと、リセットで太字や余白が消えず、`className` に渡したユーティリティクラスが効きます
310
+
311
+ ```css
312
+ /* Tailwind v4 の例:グローバル CSS の先頭で順序を宣言する */
313
+ @layer theme, base, note-blog-kit, components, utilities;
314
+ @import "tailwindcss";
315
+ ```
316
+
317
+ ```css
318
+ /* ブランド色に合わせる */
319
+ :root {
320
+ --nbk-color-accent: #e5004f;
321
+ }
322
+
323
+ /* ダークモード(既定では配色を変えません) */
324
+ @media (prefers-color-scheme: dark) {
325
+ :root {
326
+ --nbk-color-text: #f1f1f1;
327
+ --nbk-color-muted: #a3adb4;
328
+ --nbk-color-border: #333;
329
+ --nbk-color-placeholder: #222;
330
+ }
331
+ }
332
+
333
+ /* 個別の調整はクラス名で(レイヤーに入れなければ詳細度を気にせず上書きできる) */
334
+ .nbk-card__title {
335
+ font-size: 1.125rem;
336
+ }
337
+ ```
338
+
339
+ ## ライセンス
340
+
341
+ MIT
@@ -0,0 +1,32 @@
1
+ #!/usr/bin/env node
2
+
3
+ // src/cli/run.ts
4
+ import { parseArgs } from "util";
5
+ var USAGE = `\u4F7F\u3044\u65B9: note-blog-kit <command>
6
+
7
+ \u30B3\u30DE\u30F3\u30C9:
8
+ sync \u8A18\u4E8B\u3092\u53D6\u5F97\u3057\u3066 JSON \u306B\u66F8\u304D\u51FA\u3059\uFF08Phase 4 \u3067\u5B9F\u88C5\u4E88\u5B9A\uFF09`;
9
+ function run(argv) {
10
+ const { positionals, values } = parseArgs({
11
+ args: argv,
12
+ allowPositionals: true,
13
+ strict: false,
14
+ options: { help: { type: "boolean", short: "h" } }
15
+ });
16
+ const [command] = positionals;
17
+ if (values.help === true || command === void 0) {
18
+ console.log(USAGE);
19
+ return 0;
20
+ }
21
+ if (command === "sync") {
22
+ console.error("sync \u306F\u307E\u3060\u5B9F\u88C5\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002");
23
+ return 1;
24
+ }
25
+ console.error(`\u4E0D\u660E\u306A\u30B3\u30DE\u30F3\u30C9\u3067\u3059: ${command}
26
+
27
+ ${USAGE}`);
28
+ return 2;
29
+ }
30
+
31
+ // src/cli/index.ts
32
+ process.exitCode = run(process.argv.slice(2));
package/dist/index.cjs ADDED
@@ -0,0 +1,2 @@
1
+ 'use strict';
2
+
@@ -0,0 +1,76 @@
1
+ /**
2
+ * 公開型。note の生 JSON は公開せず、すべてこの型に正規化する。
3
+ * 確定の経緯は docs/phase0-findings.md を参照。変更は人の承認が必要。
4
+ */
5
+ /** 取得元 */
6
+ type NoteSource = 'api' | 'rss';
7
+ /** 記事の著者 */
8
+ interface NoteAuthor {
9
+ /** 表示名 */
10
+ name: string;
11
+ /** note.com/{urlname} の部分 */
12
+ urlname: string;
13
+ imageUrl: string | null;
14
+ }
15
+ /** 一覧に出す記事。API(v2 contents)と RSS のどちらからも作れる */
16
+ interface NoteArticleSummary {
17
+ /** 記事キー(例: n55256baa5425) */
18
+ key: string;
19
+ title: string;
20
+ /** note 上の記事 URL。canonical の既定値 */
21
+ url: string;
22
+ /** ISO 8601 */
23
+ publishedAt: string;
24
+ /** 本文先頭のプレーンテキスト。`<` などがそのまま入りうるので、HTML として挿入しないこと */
25
+ excerpt: string;
26
+ eyecatchUrl: string | null;
27
+ /** 先頭の # を除いたハッシュタグ。RSS では常に空 */
28
+ hashtags: string[];
29
+ /** RSS では null */
30
+ likeCount: number | null;
31
+ /** 価格(円)。0 は無料。RSS では null */
32
+ price: number | null;
33
+ author: NoteAuthor;
34
+ source: NoteSource;
35
+ }
36
+ /** 見出し画像 */
37
+ interface NoteEyecatch {
38
+ url: string;
39
+ width: number | null;
40
+ height: number | null;
41
+ alt: string;
42
+ }
43
+ /** 目次の項目 */
44
+ interface NoteTocItem {
45
+ /** 本文中の見出しの id */
46
+ id: string;
47
+ /** 見出しのプレーンテキスト。HTML として挿入しないこと */
48
+ text: string;
49
+ level: 2 | 3;
50
+ }
51
+ /** 本文中の埋め込み */
52
+ interface NoteEmbed {
53
+ key: string;
54
+ service: 'note' | 'external-article' | (string & {});
55
+ url: string;
56
+ }
57
+ /** 詳細ページの記事(v3 notes から作る) */
58
+ interface NoteArticle extends NoteArticleSummary {
59
+ /** サニタイズ済みの本文 HTML */
60
+ bodyHtml: string;
61
+ /** 有料部分があり、本文が途中までのとき true(「続きは note で」を出す) */
62
+ isPartial: boolean;
63
+ eyecatch: NoteEyecatch | null;
64
+ toc: NoteTocItem[];
65
+ embeds: NoteEmbed[];
66
+ }
67
+ /** 記事一覧の1ページ */
68
+ interface NoteArticlePage {
69
+ articles: NoteArticleSummary[];
70
+ page: number;
71
+ /** RSS では null */
72
+ totalCount: number | null;
73
+ isLastPage: boolean;
74
+ }
75
+
76
+ export type { NoteArticle, NoteArticlePage, NoteArticleSummary, NoteAuthor, NoteEmbed, NoteEyecatch, NoteSource, NoteTocItem };
@@ -0,0 +1,76 @@
1
+ /**
2
+ * 公開型。note の生 JSON は公開せず、すべてこの型に正規化する。
3
+ * 確定の経緯は docs/phase0-findings.md を参照。変更は人の承認が必要。
4
+ */
5
+ /** 取得元 */
6
+ type NoteSource = 'api' | 'rss';
7
+ /** 記事の著者 */
8
+ interface NoteAuthor {
9
+ /** 表示名 */
10
+ name: string;
11
+ /** note.com/{urlname} の部分 */
12
+ urlname: string;
13
+ imageUrl: string | null;
14
+ }
15
+ /** 一覧に出す記事。API(v2 contents)と RSS のどちらからも作れる */
16
+ interface NoteArticleSummary {
17
+ /** 記事キー(例: n55256baa5425) */
18
+ key: string;
19
+ title: string;
20
+ /** note 上の記事 URL。canonical の既定値 */
21
+ url: string;
22
+ /** ISO 8601 */
23
+ publishedAt: string;
24
+ /** 本文先頭のプレーンテキスト。`<` などがそのまま入りうるので、HTML として挿入しないこと */
25
+ excerpt: string;
26
+ eyecatchUrl: string | null;
27
+ /** 先頭の # を除いたハッシュタグ。RSS では常に空 */
28
+ hashtags: string[];
29
+ /** RSS では null */
30
+ likeCount: number | null;
31
+ /** 価格(円)。0 は無料。RSS では null */
32
+ price: number | null;
33
+ author: NoteAuthor;
34
+ source: NoteSource;
35
+ }
36
+ /** 見出し画像 */
37
+ interface NoteEyecatch {
38
+ url: string;
39
+ width: number | null;
40
+ height: number | null;
41
+ alt: string;
42
+ }
43
+ /** 目次の項目 */
44
+ interface NoteTocItem {
45
+ /** 本文中の見出しの id */
46
+ id: string;
47
+ /** 見出しのプレーンテキスト。HTML として挿入しないこと */
48
+ text: string;
49
+ level: 2 | 3;
50
+ }
51
+ /** 本文中の埋め込み */
52
+ interface NoteEmbed {
53
+ key: string;
54
+ service: 'note' | 'external-article' | (string & {});
55
+ url: string;
56
+ }
57
+ /** 詳細ページの記事(v3 notes から作る) */
58
+ interface NoteArticle extends NoteArticleSummary {
59
+ /** サニタイズ済みの本文 HTML */
60
+ bodyHtml: string;
61
+ /** 有料部分があり、本文が途中までのとき true(「続きは note で」を出す) */
62
+ isPartial: boolean;
63
+ eyecatch: NoteEyecatch | null;
64
+ toc: NoteTocItem[];
65
+ embeds: NoteEmbed[];
66
+ }
67
+ /** 記事一覧の1ページ */
68
+ interface NoteArticlePage {
69
+ articles: NoteArticleSummary[];
70
+ page: number;
71
+ /** RSS では null */
72
+ totalCount: number | null;
73
+ isLastPage: boolean;
74
+ }
75
+
76
+ export type { NoteArticle, NoteArticlePage, NoteArticleSummary, NoteAuthor, NoteEmbed, NoteEyecatch, NoteSource, NoteTocItem };
package/dist/index.js ADDED
@@ -0,0 +1 @@
1
+
@@ -0,0 +1,84 @@
1
+ import { NoteArticlePage, NoteArticleSummary } from './index.js';
2
+
3
+ /** 取得関数に共通するオプションの型・既定値・検証 */
4
+ /** note から取得する関数(listArticles・getArticle など)に共通するオプション */
5
+ interface NoteRequestOptions {
6
+ /**
7
+ * fetch の差し替え(テストやキャッシュ層のため)。既定は globalThis.fetch。
8
+ * 差し替えた fetch でも Cookie・認証ヘッダーを付けないこと(note の公開情報だけを取得する前提)
9
+ */
10
+ fetch?: typeof globalThis.fetch;
11
+ /** 中断用のシグナル。間隔の制限で待っている間も含め、中断したらすぐにその理由をそのまま投げる */
12
+ signal?: AbortSignal;
13
+ /** タイムアウト(ミリ秒)。1〜2147483647。既定は 10000 */
14
+ timeoutMs?: number;
15
+ /**
16
+ * 連続リクエストの最小間隔(ミリ秒)。0〜2147483647。既定は 1000。
17
+ * 送信順はプロセス全体(ESM・CJS の併用やパッケージの重複を含む)で1本の列にまとめられ、
18
+ * この呼び出しは「直前の送信から minIntervalMs 経つまで」待ってから送られる。
19
+ */
20
+ minIntervalMs?: number;
21
+ }
22
+
23
+ /** `listArticles` のオプション(`note-blog-kit/next` からも参照するため @link は使わない) */
24
+ interface ListArticlesOptions extends NoteRequestOptions {
25
+ /** note のユーザー名(note.com/{user} の部分)。英数字・_・- のみ */
26
+ user: string;
27
+ /** ページ番号(1 始まり)。既定は 1。1ページは6件 */
28
+ page?: number;
29
+ }
30
+ /**
31
+ * 記事一覧の1ページを取得する(サーバー専用。note は CORS に対応していない)。
32
+ *
33
+ * @throws {TypeError} user・page が不正なとき
34
+ * @throws {NoteNotFoundError} ユーザーが見つからないとき
35
+ * @throws {NoteHttpError} その他の 2xx でないステータス
36
+ * @throws {NoteNetworkError} 通信に失敗したとき
37
+ * @throws {NoteTimeoutError} タイムアウトしたとき
38
+ * @throws {NoteSchemaError} レスポンスの形が想定と違うとき
39
+ */
40
+ declare function listArticles(options: ListArticlesOptions): Promise<NoteArticlePage>;
41
+
42
+ /** `iterateArticles`・`listAllArticles` のオプション(`note-blog-kit/next` からも参照するため @link は使わない)。`listArticles` のオプションから `page` を除いたもの */
43
+ interface IterateArticlesOptions extends Omit<ListArticlesOptions, 'page'> {
44
+ /** 取得する最大ページ数(1 以上の整数)。既定は 20(1ページ6件なので120件) */
45
+ maxPages?: number;
46
+ }
47
+ /** 全件取得の結果のうち、記事以外の情報 */
48
+ interface IterateArticlesResult {
49
+ /** maxPages に達して打ち切ったとき true(続きのページがある可能性がある) */
50
+ truncated: boolean;
51
+ /** 最後に取得したページの totalCount */
52
+ totalCount: number | null;
53
+ /** 実際に取得したページ数 */
54
+ pages: number;
55
+ }
56
+ /** {@link listAllArticles} の結果 */
57
+ interface ListAllArticlesResult extends IterateArticlesResult {
58
+ /** 取得した記事(新しい順、key で重複を除いたもの) */
59
+ articles: NoteArticleSummary[];
60
+ }
61
+ /**
62
+ * 記事を新しい順に1件ずつ返す(サーバー専用)。最終ページか maxPages に達したら終わる。
63
+ * ページの取得には `listArticles` を使うため、取得間隔の制限・タイムアウト・中断もそのまま効く。
64
+ * 取得中にページがずれて同じ記事が再び出た場合は、`key` で重複を除く。
65
+ *
66
+ * 打ち切りの有無などはジェネレーターの戻り値(`IterateArticlesResult`)で返す。
67
+ * `for await` ではこの戻り値を受け取れないため、必要なら {@link listAllArticles} を使うか `next()` を手で回す。
68
+ *
69
+ * @throws {TypeError} maxPages などが不正なとき(呼び出した時点ではなく、最初の `next()` で投げる)
70
+ * @throws 途中のページの取得で起きたエラー(それまでに返した記事はそのまま)
71
+ */
72
+ declare function iterateArticles(options: IterateArticlesOptions): AsyncGenerator<NoteArticleSummary, IterateArticlesResult, undefined>;
73
+ /**
74
+ * 全件(maxPages まで。既定は 20 ページ)を配列で返す(サーバー専用)。
75
+ * `truncated` が true なら maxPages で打ち切っており、続きのページがある可能性がある。
76
+ *
77
+ * @throws {TypeError} maxPages などが不正なとき
78
+ * @throws 途中のページの取得で起きたエラー。それまでに集めた記事は返らない
79
+ * (途中までの記事も使いたい場合は {@link iterateArticles} を使う)
80
+ */
81
+ declare function listAllArticles(options: IterateArticlesOptions): Promise<ListAllArticlesResult>;
82
+
83
+ export { listArticles as c, iterateArticles as i, listAllArticles as l };
84
+ export type { IterateArticlesOptions as I, ListArticlesOptions as L, NoteRequestOptions as N, IterateArticlesResult as a, ListAllArticlesResult as b };