katanakit-js 3.1.2 → 3.2.1
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/README.md +559 -0
- package/dist/adapters/index.d.ts +2 -0
- package/dist/adapters/index.d.ts.map +1 -1
- package/dist/adapters/index.js +2 -0
- package/dist/adapters/index.js.map +1 -1
- package/dist/adapters/notion/index.d.ts +3 -0
- package/dist/adapters/notion/index.d.ts.map +1 -0
- package/dist/adapters/notion/index.js +2 -0
- package/dist/adapters/notion/index.js.map +1 -0
- package/dist/adapters/notion/notion.service.d.ts +397 -0
- package/dist/adapters/notion/notion.service.d.ts.map +1 -0
- package/dist/adapters/notion/notion.service.js +604 -0
- package/dist/adapters/notion/notion.service.js.map +1 -0
- package/dist/adapters/wordpress/index.d.ts +3 -0
- package/dist/adapters/wordpress/index.d.ts.map +1 -0
- package/dist/adapters/wordpress/index.js +2 -0
- package/dist/adapters/wordpress/index.js.map +1 -0
- package/dist/adapters/wordpress/wordpress.service.d.ts +685 -0
- package/dist/adapters/wordpress/wordpress.service.d.ts.map +1 -0
- package/dist/adapters/wordpress/wordpress.service.js +1100 -0
- package/dist/adapters/wordpress/wordpress.service.js.map +1 -0
- package/dist/types/index.d.ts +767 -0
- package/dist/types/index.d.ts.map +1 -1
- package/package.json +14 -2
package/README.md
CHANGED
|
@@ -565,6 +565,565 @@ See [Getting Started](https://senseikatana.com/katanakit-js/docs/guides/getting-
|
|
|
565
565
|
| **Telegram** | `katanakit-js/adapters/telegram` | BotFather bot (`useInitTelegram`, `useStartTelegramPolling`) |
|
|
566
566
|
| **WhatsApp** | `katanakit-js/adapters/whatsapp` | Meta Cloud API (`useInitWhatsApp`, `useStartWhatsApp`) |
|
|
567
567
|
|
|
568
|
+
## REST API Adapters
|
|
569
|
+
|
|
570
|
+
Typed adapters for popular REST APIs with auth, pagination helpers, and full TypeScript types.
|
|
571
|
+
All functions return `FetchResult<T>` — the same Safe Result pattern used by the HTTP client.
|
|
572
|
+
|
|
573
|
+
| Adapter | Import | Description |
|
|
574
|
+
|---------|--------|-------------|
|
|
575
|
+
| **Notion** | `katanakit-js/adapters/notion` | Pages, databases, blocks, search with cursor pagination |
|
|
576
|
+
| **WordPress** | `katanakit-js/adapters/wordpress` | Posts, pages, media, categories, tags, comments, users, batch ops |
|
|
577
|
+
|
|
578
|
+
### Notion
|
|
579
|
+
|
|
580
|
+
The Notion adapter wraps the official [Notion API](https://developers.notion.com/reference) with
|
|
581
|
+
full TypeScript types, cursor-based auto-pagination, and Safe Results.
|
|
582
|
+
|
|
583
|
+
#### Setup
|
|
584
|
+
|
|
585
|
+
```ts
|
|
586
|
+
import { useInitNotion } from "katanakit-js/adapters/notion";
|
|
587
|
+
|
|
588
|
+
// Token starts with "ntn_" or "secret_" — get one at https://www.notion.so/my-integrations
|
|
589
|
+
useInitNotion({ token: process.env.NOTION_TOKEN });
|
|
590
|
+
```
|
|
591
|
+
|
|
592
|
+
#### Pages — read, create, update, archive
|
|
593
|
+
|
|
594
|
+
```ts
|
|
595
|
+
import {
|
|
596
|
+
useNotionGetPage,
|
|
597
|
+
useNotionCreatePage,
|
|
598
|
+
useNotionUpdatePage,
|
|
599
|
+
useNotionArchivePage,
|
|
600
|
+
} from "katanakit-js/adapters/notion";
|
|
601
|
+
|
|
602
|
+
// Get a single page with all its properties
|
|
603
|
+
const page = await useNotionGetPage("page-id");
|
|
604
|
+
if (page.ok) console.log(page.data.properties);
|
|
605
|
+
|
|
606
|
+
// Create a page inside a database
|
|
607
|
+
const created = await useNotionCreatePage(
|
|
608
|
+
{ type: "database_id", database_id: "db-id" },
|
|
609
|
+
{
|
|
610
|
+
Name: { title: [{ type: "text", text: { content: "My Task" } }] },
|
|
611
|
+
Status: { select: { name: "To Do" } },
|
|
612
|
+
},
|
|
613
|
+
);
|
|
614
|
+
|
|
615
|
+
// Create a child page with content blocks
|
|
616
|
+
const child = await useNotionCreatePage(
|
|
617
|
+
{ type: "page_id", page_id: "parent-id" },
|
|
618
|
+
{ title: { title: [{ type: "text", text: { content: "Child Page" } }] } },
|
|
619
|
+
[{ type: "paragraph", paragraph: { rich_text: [{ type: "text", text: { content: "Hello!" } }] } }],
|
|
620
|
+
);
|
|
621
|
+
|
|
622
|
+
// Update page properties (only changed fields)
|
|
623
|
+
await useNotionUpdatePage("page-id", {
|
|
624
|
+
Status: { select: { name: "Done" } },
|
|
625
|
+
DueDate: { date: { start: "2025-12-31" } },
|
|
626
|
+
});
|
|
627
|
+
|
|
628
|
+
// Archive (soft-delete) a page
|
|
629
|
+
await useNotionArchivePage("page-id");
|
|
630
|
+
```
|
|
631
|
+
|
|
632
|
+
#### Databases — query, create, update schema
|
|
633
|
+
|
|
634
|
+
```ts
|
|
635
|
+
import {
|
|
636
|
+
useNotionGetDatabase,
|
|
637
|
+
useNotionQueryDatabase,
|
|
638
|
+
useNotionCreateDatabase,
|
|
639
|
+
useNotionUpdateDatabase,
|
|
640
|
+
useNotionListAllDatabasePages,
|
|
641
|
+
} from "katanakit-js/adapters/notion";
|
|
642
|
+
|
|
643
|
+
// Inspect database schema (property names, types, options)
|
|
644
|
+
const schema = await useNotionGetDatabase("db-id");
|
|
645
|
+
if (schema.ok) {
|
|
646
|
+
Object.entries(schema.data.properties).forEach(([name, prop]) => {
|
|
647
|
+
console.log(`${name}: ${prop.type}`);
|
|
648
|
+
});
|
|
649
|
+
}
|
|
650
|
+
|
|
651
|
+
// Query with filter + sort (single page of results)
|
|
652
|
+
const page1 = await useNotionQueryDatabase("db-id", {
|
|
653
|
+
filter: { property: "Status", select: { equals: "Published" } },
|
|
654
|
+
sorts: [{ property: "Date", direction: "descending" }],
|
|
655
|
+
page_size: 10,
|
|
656
|
+
});
|
|
657
|
+
|
|
658
|
+
// Get ALL pages (auto-pagination — handles cursors internally)
|
|
659
|
+
const all = await useNotionListAllDatabasePages("db-id");
|
|
660
|
+
|
|
661
|
+
// With filter + sort
|
|
662
|
+
const published = await useNotionListAllDatabasePages(
|
|
663
|
+
"db-id",
|
|
664
|
+
{ property: "Status", select: { equals: "Published" } },
|
|
665
|
+
[{ property: "Date", direction: "descending" }],
|
|
666
|
+
);
|
|
667
|
+
|
|
668
|
+
// Create a new database
|
|
669
|
+
await useNotionCreateDatabase(
|
|
670
|
+
{ type: "page_id", page_id: "parent-id" },
|
|
671
|
+
[{ type: "text", text: { content: "My Tasks" } }],
|
|
672
|
+
{
|
|
673
|
+
Name: { title: {} },
|
|
674
|
+
Status: { select: { options: [{ name: "To Do" }, { name: "Done" }] } },
|
|
675
|
+
Priority: { select: { options: [{ name: "Low" }, { name: "High" }] } },
|
|
676
|
+
},
|
|
677
|
+
);
|
|
678
|
+
|
|
679
|
+
// Rename a database
|
|
680
|
+
await useNotionUpdateDatabase("db-id", [
|
|
681
|
+
{ type: "text", text: { content: "Renamed Database" } },
|
|
682
|
+
]);
|
|
683
|
+
```
|
|
684
|
+
|
|
685
|
+
#### Blocks — read, write, append, delete page content
|
|
686
|
+
|
|
687
|
+
```ts
|
|
688
|
+
import {
|
|
689
|
+
useNotionGetBlock,
|
|
690
|
+
useNotionGetBlockChildren,
|
|
691
|
+
useNotionListAllBlockChildren,
|
|
692
|
+
useNotionAppendBlocks,
|
|
693
|
+
useNotionUpdateBlock,
|
|
694
|
+
useNotionDeleteBlock,
|
|
695
|
+
} from "katanakit-js/adapters/notion";
|
|
696
|
+
|
|
697
|
+
// Get ALL blocks of a page (auto-pagination)
|
|
698
|
+
const blocks = await useNotionListAllBlockChildren("page-id");
|
|
699
|
+
if (blocks.ok) {
|
|
700
|
+
blocks.data.forEach(b => console.log(b.type)); // "paragraph", "heading_1", etc.
|
|
701
|
+
}
|
|
702
|
+
|
|
703
|
+
// Manual pagination (for fine-grained cursor control)
|
|
704
|
+
const page = await useNotionGetBlockChildren("page-id", { page_size: 50 });
|
|
705
|
+
if (page.ok) {
|
|
706
|
+
console.log(page.data.results); // blocks
|
|
707
|
+
console.log(page.data.has_more); // true if more pages exist
|
|
708
|
+
console.log(page.data.next_cursor); // pass as start_cursor for next page
|
|
709
|
+
}
|
|
710
|
+
|
|
711
|
+
// Append content blocks to a page
|
|
712
|
+
await useNotionAppendBlocks("page-id", [
|
|
713
|
+
{
|
|
714
|
+
type: "heading_2",
|
|
715
|
+
heading_2: { rich_text: [{ type: "text", text: { content: "New Section" } }] },
|
|
716
|
+
},
|
|
717
|
+
{
|
|
718
|
+
type: "paragraph",
|
|
719
|
+
paragraph: { rich_text: [{ type: "text", text: { content: "Body text here." } }] },
|
|
720
|
+
},
|
|
721
|
+
{
|
|
722
|
+
type: "to_do",
|
|
723
|
+
to_do: {
|
|
724
|
+
rich_text: [{ type: "text", text: { content: "Checklist item" } }],
|
|
725
|
+
checked: false,
|
|
726
|
+
},
|
|
727
|
+
},
|
|
728
|
+
]);
|
|
729
|
+
|
|
730
|
+
// Update a block's content
|
|
731
|
+
await useNotionUpdateBlock("block-id", {
|
|
732
|
+
paragraph: { rich_text: [{ type: "text", text: { content: "Updated text" } }] },
|
|
733
|
+
});
|
|
734
|
+
|
|
735
|
+
// Delete (archive) a block
|
|
736
|
+
await useNotionDeleteBlock("block-id");
|
|
737
|
+
```
|
|
738
|
+
|
|
739
|
+
#### Search — find pages and databases by keyword
|
|
740
|
+
|
|
741
|
+
```ts
|
|
742
|
+
import { useNotionSearchContent } from "katanakit-js/adapters/notion";
|
|
743
|
+
|
|
744
|
+
// Search everything
|
|
745
|
+
const found = await useNotionSearchContent({ query: "meeting notes" });
|
|
746
|
+
|
|
747
|
+
// Search only databases
|
|
748
|
+
const dbs = await useNotionSearchContent({
|
|
749
|
+
query: "tasks",
|
|
750
|
+
filter: { value: "database", property: "object" },
|
|
751
|
+
});
|
|
752
|
+
|
|
753
|
+
// Search only pages, sorted by recently edited
|
|
754
|
+
const pages = await useNotionSearchContent({
|
|
755
|
+
filter: { value: "page", property: "object" },
|
|
756
|
+
sort: { direction: "descending", timestamp: "last_edited_time" },
|
|
757
|
+
});
|
|
758
|
+
```
|
|
759
|
+
|
|
760
|
+
#### Users — workspace members
|
|
761
|
+
|
|
762
|
+
```ts
|
|
763
|
+
import { useNotionGetUser, useNotionListUsers } from "katanakit-js/adapters/notion";
|
|
764
|
+
|
|
765
|
+
// Get a specific user (from page.created_by.id or page.last_edited_by.id)
|
|
766
|
+
const user = await useNotionGetUser("user-id");
|
|
767
|
+
if (user.ok) console.log(user.data.name);
|
|
768
|
+
|
|
769
|
+
// List all workspace members + bots
|
|
770
|
+
const users = await useNotionListUsers();
|
|
771
|
+
if (users.ok) users.data.results.forEach(u => console.log(u.name));
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
#### Framework examples
|
|
775
|
+
|
|
776
|
+
| Framework | Example | Description |
|
|
777
|
+
|-----------|---------|-------------|
|
|
778
|
+
| **Vue 3** | [`examples/notion/vue-blog.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/vue-blog.vue) | Blog listing with `useQuery` composable |
|
|
779
|
+
| **Vue 3** | [`examples/notion/vue-post.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/vue-post.vue) | Single post view |
|
|
780
|
+
| **Nuxt 3** | [`examples/notion/nuxt-blog.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/nuxt-blog.vue) | SSR blog listing with `useAsyncData` |
|
|
781
|
+
| **Nuxt 3** | [`examples/notion/nuxt-post.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/nuxt-post.vue) | SSR single post view |
|
|
782
|
+
| **Astro** | [`examples/notion/astro-blog.astro`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/astro-blog.astro) | Static blog listing |
|
|
783
|
+
| **Astro** | [`examples/notion/astro-[slug].astro`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/astro-[slug].astro) | Dynamic `[slug]` route |
|
|
784
|
+
| **Next.js** | [`examples/notion/next-blog.tsx`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/next-blog.tsx) | Server component blog listing |
|
|
785
|
+
| **Next.js** | [`examples/notion/next-[slug].tsx`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/next-[slug].tsx) | Dynamic `[slug]` page |
|
|
786
|
+
| **Node.js** | [`examples/notion/demo.ts`](https://github.com/senseikatana/katanakit-js/tree/main/examples/notion/demo.ts) | Runnable demo covering all Notion operations |
|
|
787
|
+
|
|
788
|
+
### WordPress
|
|
789
|
+
|
|
790
|
+
The WordPress adapter wraps the [WordPress REST API](https://developer.wordpress.org/rest-api/)
|
|
791
|
+
with full CRUD for posts, pages, media, categories, tags, comments, users, custom post types,
|
|
792
|
+
and batch operations. All functions return `FetchResult<T>`.
|
|
793
|
+
|
|
794
|
+
#### Setup
|
|
795
|
+
|
|
796
|
+
```ts
|
|
797
|
+
import { useInitWordPress } from "katanakit-js/adapters/wordpress";
|
|
798
|
+
|
|
799
|
+
// Application Passwords (recommended) — WP Admin → Users → Your Profile → Application Passwords
|
|
800
|
+
useInitWordPress({
|
|
801
|
+
baseUrl: "https://mysite.com",
|
|
802
|
+
auth: { type: "application-passwords", username: "admin", password: "xxxx xxxx xxxx" },
|
|
803
|
+
});
|
|
804
|
+
|
|
805
|
+
// JWT tokens
|
|
806
|
+
useInitWordPress({
|
|
807
|
+
baseUrl: "https://mysite.com",
|
|
808
|
+
auth: { type: "jwt", token: "eyJhbGci..." },
|
|
809
|
+
});
|
|
810
|
+
|
|
811
|
+
// Nonce-based (for WP themes)
|
|
812
|
+
useInitWordPress({
|
|
813
|
+
baseUrl: "https://mysite.com",
|
|
814
|
+
auth: { type: "nonce", nonce: "abc123" },
|
|
815
|
+
});
|
|
816
|
+
```
|
|
817
|
+
|
|
818
|
+
#### Posts — CRUD, search, pagination
|
|
819
|
+
|
|
820
|
+
```ts
|
|
821
|
+
import {
|
|
822
|
+
useWpGetPosts,
|
|
823
|
+
useWpGetPost,
|
|
824
|
+
useWpCreatePost,
|
|
825
|
+
useWpUpdatePost,
|
|
826
|
+
useWpDeletePost,
|
|
827
|
+
useWpListAllPosts,
|
|
828
|
+
useWpSearchAllPosts,
|
|
829
|
+
useWpFindPostBySlug,
|
|
830
|
+
} from "katanakit-js/adapters/wordpress";
|
|
831
|
+
|
|
832
|
+
// List published posts (paginated)
|
|
833
|
+
const posts = await useWpGetPosts({
|
|
834
|
+
per_page: 5,
|
|
835
|
+
status: "publish",
|
|
836
|
+
orderby: "date",
|
|
837
|
+
order: "desc",
|
|
838
|
+
});
|
|
839
|
+
|
|
840
|
+
// Get a single post with embedded resources
|
|
841
|
+
const post = await useWpGetPost(42, { _embed: true });
|
|
842
|
+
if (post.ok) console.log(post.data.title.rendered);
|
|
843
|
+
|
|
844
|
+
// Create a post
|
|
845
|
+
await useWpCreatePost({
|
|
846
|
+
title: "My New Post",
|
|
847
|
+
content: "<p>Hello World!</p>",
|
|
848
|
+
status: "publish", // "draft" | "pending" | "publish"
|
|
849
|
+
categories: [1, 3],
|
|
850
|
+
tags: [5, 8],
|
|
851
|
+
});
|
|
852
|
+
|
|
853
|
+
// Update a post
|
|
854
|
+
await useWpUpdatePost(42, { title: "Updated Title", status: "publish" });
|
|
855
|
+
|
|
856
|
+
// Delete (trash or permanent)
|
|
857
|
+
await useWpDeletePost(42); // move to trash
|
|
858
|
+
await useWpDeletePost(42, true); // permanently delete
|
|
859
|
+
|
|
860
|
+
// Get ALL posts (auto-pagination — loops until exhausted)
|
|
861
|
+
const all = await useWpListAllPosts({ status: "publish" });
|
|
862
|
+
if (all.ok) console.log(`Total: ${all.data.length}`);
|
|
863
|
+
|
|
864
|
+
// Search ALL posts by keyword
|
|
865
|
+
const found = await useWpSearchAllPosts("tutorial");
|
|
866
|
+
if (found.ok) found.data.forEach(p => console.log(p.title.rendered));
|
|
867
|
+
|
|
868
|
+
// Find post by slug (for dynamic routes like /blog/:slug)
|
|
869
|
+
const bySlug = await useWpFindPostBySlug("hello-world");
|
|
870
|
+
if (bySlug.ok && bySlug.data) console.log(bySlug.data.title.rendered);
|
|
871
|
+
```
|
|
872
|
+
|
|
873
|
+
#### Pages — static content CRUD
|
|
874
|
+
|
|
875
|
+
```ts
|
|
876
|
+
import {
|
|
877
|
+
useWpGetPages,
|
|
878
|
+
useWpGetPage,
|
|
879
|
+
useWpCreatePage,
|
|
880
|
+
useWpUpdatePage,
|
|
881
|
+
useWpDeletePage,
|
|
882
|
+
} from "katanakit-js/adapters/wordpress";
|
|
883
|
+
|
|
884
|
+
const pages = await useWpGetPages({ per_page: 20 });
|
|
885
|
+
|
|
886
|
+
const page = await useWpGetPage(10);
|
|
887
|
+
if (page.ok) console.log(page.data.title.rendered);
|
|
888
|
+
|
|
889
|
+
await useWpCreatePage({
|
|
890
|
+
title: "About Us",
|
|
891
|
+
content: "<p>Welcome to our site!</p>",
|
|
892
|
+
status: "publish",
|
|
893
|
+
parent: 0, // top-level page (set a page ID for child pages)
|
|
894
|
+
});
|
|
895
|
+
|
|
896
|
+
await useWpUpdatePage(10, { title: "Updated About" });
|
|
897
|
+
await useWpDeletePage(10); // trash
|
|
898
|
+
```
|
|
899
|
+
|
|
900
|
+
#### Media — upload, list, update, delete
|
|
901
|
+
|
|
902
|
+
```ts
|
|
903
|
+
import {
|
|
904
|
+
useWpGetMedia,
|
|
905
|
+
useWpGetMediaItem,
|
|
906
|
+
useWpUploadMedia,
|
|
907
|
+
useWpUpdateMedia,
|
|
908
|
+
useWpDeleteMedia,
|
|
909
|
+
} from "katanakit-js/adapters/wordpress";
|
|
910
|
+
|
|
911
|
+
// List media items
|
|
912
|
+
const media = await useWpGetMedia({ per_page: 20, media_type: "image" });
|
|
913
|
+
|
|
914
|
+
// Get a single media item
|
|
915
|
+
const item = await useWpGetMediaItem(42);
|
|
916
|
+
if (item.ok) console.log(item.data.source_url);
|
|
917
|
+
|
|
918
|
+
// Upload from browser (File from <input type="file">)
|
|
919
|
+
const file = document.querySelector("input[type=file]").files[0];
|
|
920
|
+
const uploaded = await useWpUploadMedia(file, {
|
|
921
|
+
title: "My Image",
|
|
922
|
+
alt_text: "Description for accessibility",
|
|
923
|
+
caption: "Image caption",
|
|
924
|
+
});
|
|
925
|
+
if (uploaded.ok) console.log(uploaded.data.source_url); // URL to use in content
|
|
926
|
+
|
|
927
|
+
// Upload from Node.js (Buffer)
|
|
928
|
+
import fs from "node:fs";
|
|
929
|
+
const buffer = fs.readFileSync("photo.jpg");
|
|
930
|
+
await useWpUploadMedia(buffer, { title: "Photo" });
|
|
931
|
+
|
|
932
|
+
// Update media metadata
|
|
933
|
+
await useWpUpdateMedia(42, { alt_text: "New alt text", caption: "Updated caption" });
|
|
934
|
+
|
|
935
|
+
// Delete media
|
|
936
|
+
await useWpDeleteMedia(42, true); // permanent
|
|
937
|
+
```
|
|
938
|
+
|
|
939
|
+
#### Categories and Tags — taxonomy management
|
|
940
|
+
|
|
941
|
+
```ts
|
|
942
|
+
import {
|
|
943
|
+
useWpGetCategories, useWpGetCategory, useWpCreateCategory,
|
|
944
|
+
useWpUpdateCategory, useWpDeleteCategory,
|
|
945
|
+
useWpGetTags, useWpGetTag, useWpCreateTag,
|
|
946
|
+
useWpUpdateTag, useWpDeleteTag,
|
|
947
|
+
} from "katanakit-js/adapters/wordpress";
|
|
948
|
+
|
|
949
|
+
// Categories
|
|
950
|
+
const cats = await useWpGetCategories({ per_page: 50 });
|
|
951
|
+
await useWpCreateCategory({ name: "Technology", slug: "tech", description: "Tech posts" });
|
|
952
|
+
await useWpUpdateCategory(5, { name: "Tech News" });
|
|
953
|
+
await useWpDeleteCategory(5);
|
|
954
|
+
|
|
955
|
+
// Tags
|
|
956
|
+
const tags = await useWpGetTags({ search: "javascript" });
|
|
957
|
+
await useWpCreateTag({ name: "TypeScript", slug: "typescript" });
|
|
958
|
+
await useWpUpdateTag(12, { name: "TS" });
|
|
959
|
+
await useWpDeleteTag(12);
|
|
960
|
+
```
|
|
961
|
+
|
|
962
|
+
#### Comments — moderation
|
|
963
|
+
|
|
964
|
+
```ts
|
|
965
|
+
import {
|
|
966
|
+
useWpGetComments, useWpGetComment, useWpCreateComment,
|
|
967
|
+
useWpUpdateComment, useWpDeleteComment,
|
|
968
|
+
} from "katanakit-js/adapters/wordpress";
|
|
969
|
+
|
|
970
|
+
// Get comments for a post
|
|
971
|
+
const comments = await useWpGetComments({ post: 42, per_page: 10 });
|
|
972
|
+
|
|
973
|
+
// Create a comment (public or authenticated)
|
|
974
|
+
await useWpCreateComment({
|
|
975
|
+
post: 42,
|
|
976
|
+
content: "Great article!",
|
|
977
|
+
author_name: "John",
|
|
978
|
+
author_email: "john@example.com",
|
|
979
|
+
});
|
|
980
|
+
|
|
981
|
+
// Update / delete
|
|
982
|
+
await useWpUpdateComment(7, { content: "Updated comment" });
|
|
983
|
+
await useWpDeleteComment(7);
|
|
984
|
+
```
|
|
985
|
+
|
|
986
|
+
#### Users — management
|
|
987
|
+
|
|
988
|
+
```ts
|
|
989
|
+
import {
|
|
990
|
+
useWpGetUsers, useWpGetUser, useWpGetCurrentUser,
|
|
991
|
+
useWpCreateUser, useWpUpdateUser, useWpDeleteUser,
|
|
992
|
+
} from "katanakit-js/adapters/wordpress";
|
|
993
|
+
|
|
994
|
+
const users = await useWpGetUsers({ roles: "editor" });
|
|
995
|
+
const me = await useWpGetCurrentUser(); // authenticated user
|
|
996
|
+
|
|
997
|
+
await useWpCreateUser({
|
|
998
|
+
username: "johndoe",
|
|
999
|
+
email: "john@example.com",
|
|
1000
|
+
password: "secure-password",
|
|
1001
|
+
roles: ["editor"],
|
|
1002
|
+
});
|
|
1003
|
+
|
|
1004
|
+
await useWpUpdateUser(2, { name: "John Smith" });
|
|
1005
|
+
await useWpDeleteUser(2, 1); // reassign content to user 1
|
|
1006
|
+
```
|
|
1007
|
+
|
|
1008
|
+
#### Custom Post Types — generic CRUD
|
|
1009
|
+
|
|
1010
|
+
```ts
|
|
1011
|
+
import {
|
|
1012
|
+
useWpGetCustomPosts, useWpGetCustomPost,
|
|
1013
|
+
useWpCreateCustomPost, useWpUpdateCustomPost, useWpDeleteCustomPost,
|
|
1014
|
+
} from "katanakit-js/adapters/wordpress";
|
|
1015
|
+
|
|
1016
|
+
// Works with any registered CPT: "product", "portfolio", "event", etc.
|
|
1017
|
+
const products = await useWpGetCustomPosts("product", { per_page: 10 });
|
|
1018
|
+
const product = await useWpGetCustomPost("product", 15);
|
|
1019
|
+
|
|
1020
|
+
await useWpCreateCustomPost("product", {
|
|
1021
|
+
title: "Widget",
|
|
1022
|
+
content: "<p>A great widget</p>",
|
|
1023
|
+
status: "publish",
|
|
1024
|
+
});
|
|
1025
|
+
|
|
1026
|
+
await useWpUpdateCustomPost("product", 15, { title: "Updated Widget" });
|
|
1027
|
+
await useWpDeleteCustomPost("product", 15, true);
|
|
1028
|
+
```
|
|
1029
|
+
|
|
1030
|
+
#### Batch Operations — multiple requests in one call
|
|
1031
|
+
|
|
1032
|
+
```ts
|
|
1033
|
+
import { useWpBatch } from "katanakit-js/adapters/wordpress";
|
|
1034
|
+
|
|
1035
|
+
const result = await useWpBatch([
|
|
1036
|
+
{ method: "GET", path: "/wp/v2/posts?per_page=2" },
|
|
1037
|
+
{ method: "GET", path: "/wp/v2/pages?per_page=2" },
|
|
1038
|
+
{ method: "GET", path: "/wp/v2/categories?per_page=5" },
|
|
1039
|
+
]);
|
|
1040
|
+
|
|
1041
|
+
if (result.ok) {
|
|
1042
|
+
result.data.responses.forEach(resp => console.log(resp.status));
|
|
1043
|
+
}
|
|
1044
|
+
```
|
|
1045
|
+
|
|
1046
|
+
#### `_fields` — minimal payloads
|
|
1047
|
+
|
|
1048
|
+
Use `_fields` to request only the fields you need. This reduces payload size
|
|
1049
|
+
significantly for list views.
|
|
1050
|
+
|
|
1051
|
+
```ts
|
|
1052
|
+
// Only fetch id, title, link, slug, and date
|
|
1053
|
+
const posts = await useWpGetPosts({
|
|
1054
|
+
per_page: 20,
|
|
1055
|
+
_fields: "id,title,link,slug,date",
|
|
1056
|
+
});
|
|
1057
|
+
```
|
|
1058
|
+
|
|
1059
|
+
#### `_embed` — embedded resources
|
|
1060
|
+
|
|
1061
|
+
Use `_embed` to include related resources (author, featured media, terms)
|
|
1062
|
+
in a single request instead of making separate calls.
|
|
1063
|
+
|
|
1064
|
+
```ts
|
|
1065
|
+
// Embed all related resources
|
|
1066
|
+
const posts = await useWpGetPosts({ _embed: true });
|
|
1067
|
+
|
|
1068
|
+
// Embed only specific resources
|
|
1069
|
+
const posts = await useWpGetPosts({
|
|
1070
|
+
_embed: "author,wp:featuredmedia",
|
|
1071
|
+
});
|
|
1072
|
+
|
|
1073
|
+
// Access embedded data
|
|
1074
|
+
if (posts.ok) {
|
|
1075
|
+
for (const post of posts.data) {
|
|
1076
|
+
const author = post._embedded?.author?.[0]?.name;
|
|
1077
|
+
const image = post._embedded?.["wp:featuredmedia"]?.[0]?.source_url;
|
|
1078
|
+
const thumbnail = post._embedded?.["wp:featuredmedia"]?.[0]?.media_details?.sizes?.thumbnail?.source_url;
|
|
1079
|
+
}
|
|
1080
|
+
}
|
|
1081
|
+
```
|
|
1082
|
+
|
|
1083
|
+
#### ACF — Advanced Custom Fields
|
|
1084
|
+
|
|
1085
|
+
If your WordPress site uses [ACF](https://www.advancedcustomfields.com/), the adapter
|
|
1086
|
+
handles ACF fields transparently. Access them via the `acf` property on any post, page,
|
|
1087
|
+
media item, or custom post type entry.
|
|
1088
|
+
|
|
1089
|
+
```ts
|
|
1090
|
+
// Request ACF fields explicitly with _fields
|
|
1091
|
+
const posts = await useWpGetPosts({
|
|
1092
|
+
per_page: 5,
|
|
1093
|
+
_fields: "id,title,acf",
|
|
1094
|
+
});
|
|
1095
|
+
|
|
1096
|
+
if (posts.ok) {
|
|
1097
|
+
for (const post of posts.data) {
|
|
1098
|
+
if (post.acf) {
|
|
1099
|
+
// ACF fields are dynamic — access by field name
|
|
1100
|
+
console.log(post.acf.my_field_name);
|
|
1101
|
+
}
|
|
1102
|
+
}
|
|
1103
|
+
}
|
|
1104
|
+
|
|
1105
|
+
// Combine _fields + _embed + ACF for full-featured list views
|
|
1106
|
+
const full = await useWpGetPosts({
|
|
1107
|
+
per_page: 5,
|
|
1108
|
+
_fields: "id,title,link,slug,date,acf",
|
|
1109
|
+
_embed: "author,wp:featuredmedia",
|
|
1110
|
+
});
|
|
1111
|
+
```
|
|
1112
|
+
|
|
1113
|
+
#### Framework examples
|
|
1114
|
+
|
|
1115
|
+
| Framework | Example | Description |
|
|
1116
|
+
|-----------|---------|-------------|
|
|
1117
|
+
| **Vue 3** | [`examples/wordpress/vue-blog.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/vue-blog.vue) | Blog listing with categories, featured images, `_embed` |
|
|
1118
|
+
| **Vue 3** | [`examples/wordpress/vue-post.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/vue-post.vue) | Single post view with embedded author |
|
|
1119
|
+
| **Nuxt 3** | [`examples/wordpress/nuxt-blog.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/nuxt-blog.vue) | SSR blog listing with `useAsyncData` |
|
|
1120
|
+
| **Nuxt 3** | [`examples/wordpress/nuxt-post.vue`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/nuxt-post.vue) | SSR single post view |
|
|
1121
|
+
| **Astro** | [`examples/wordpress/astro-blog.astro`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/astro-blog.astro) | Static blog listing |
|
|
1122
|
+
| **Astro** | [`examples/wordpress/astro-[slug].astro`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/astro-[slug].astro) | Dynamic `[slug]` route |
|
|
1123
|
+
| **Next.js** | [`examples/wordpress/next-blog.tsx`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/next-blog.tsx) | Server component blog listing |
|
|
1124
|
+
| **Next.js** | [`examples/wordpress/next-[slug].tsx`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/next-[slug].tsx) | Dynamic `[slug]` page |
|
|
1125
|
+
| **Node.js** | [`examples/wordpress/demo.ts`](https://github.com/senseikatana/katanakit-js/tree/main/examples/wordpress/demo.ts) | Runnable demo covering all WP operations, `_fields`, `_embed`, ACF |
|
|
1126
|
+
|
|
568
1127
|
## Documentation
|
|
569
1128
|
|
|
570
1129
|
The docs site is deployed with Render at [senseikatana.com/katanakit-js](https://senseikatana.com/katanakit-js/).
|
package/dist/adapters/index.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}
|
package/dist/adapters/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
export type { NotionBlock, NotionBlockList, NotionConfig, NotionDatabase, NotionDatabaseQuery, NotionFilter, NotionPage, NotionPageList, NotionParent, NotionPropertySchema, NotionRichText, NotionSearchQuery, NotionSearchResult, NotionSort, NotionUser, NotionUserList, } from "../../types/index.js";
|
|
2
|
+
export { useInitNotion, useNotionAppendBlocks, useNotionArchivePage, useNotionCreateDatabase, useNotionCreatePage, useNotionDeleteBlock, useNotionGetBlock, useNotionGetBlockChildren, useNotionGetDatabase, useNotionGetPage, useNotionGetUser, useNotionListAllBlockChildren, useNotionListAllDatabasePages, useNotionListUsers, useNotionQueryDatabase, useNotionSearchContent, useNotionUpdateBlock, useNotionUpdateDatabase, useNotionUpdatePage, } from "./notion.service.js";
|
|
3
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/notion/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,WAAW,EACX,eAAe,EACf,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,cAAc,GACd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACN,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,6BAA6B,EAC7B,6BAA6B,EAC7B,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,GACnB,MAAM,qBAAqB,CAAC"}
|
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
export { useInitNotion, useNotionAppendBlocks, useNotionArchivePage, useNotionCreateDatabase, useNotionCreatePage, useNotionDeleteBlock, useNotionGetBlock, useNotionGetBlockChildren, useNotionGetDatabase, useNotionGetPage, useNotionGetUser, useNotionListAllBlockChildren, useNotionListAllDatabasePages, useNotionListUsers, useNotionQueryDatabase, useNotionSearchContent, useNotionUpdateBlock, useNotionUpdateDatabase, useNotionUpdatePage, } from "./notion.service.js";
|
|
2
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/notion/index.ts"],"names":[],"mappings":"AAkBA,OAAO,EACN,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,6BAA6B,EAC7B,6BAA6B,EAC7B,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,GACnB,MAAM,qBAAqB,CAAC"}
|