arroact-umbraco-graphql-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Arroact
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# @arroact/umbraco-graphql-sdk
+
+TypeScript SDK for Umbraco GraphQL headless CMS integration.
+
+## 🚀 Features
+
+- ✅ **TypeScript First** - Full type safety and IntelliSense support
+- ✅ **Environment Aware** - Different behaviors for dev/staging/production
+- ✅ **Zero Configuration** - Works out of the box with sensible defaults
+- ✅ **Extensible** - Easy to extend with custom queries and models
+- ✅ **Production Ready** - Built with enterprise patterns
+- ✅ **Tree Shakeable** - ESM and CJS builds included
+
+## 📦 Installation
+
+```bash
+npm install @arroact/umbraco-graphql-sdk graphql
+```
+
+## 🔧 Usage
+
+### Basic Setup
+
+```typescript
+import { HeadlessSDK } from '@arroact/umbraco-graphql-sdk';
+
+const sdk = new HeadlessSDK({
+  environment: 'development',
+  graphqlUrl: 'https://your-umbraco-site.com/graphql',
+  apiKey: 'your-api-key', // optional
+  rootContentId: 'root-id', // optional
+  enableLogging: true, // optional
+  enableCache: false, // optional
+});
+```
+
+### Fetching Pages
+
+```typescript
+// Get a page by slug
+const page = await sdk.getPageBySlug('about-us');
+
+if (page) {
+  console.log(page.title);
+  console.log(page.content);
+  console.log(page.metaTitle);
+  console.log(page.metaDescription);
+}
+```
+
+### Next.js Integration
+
+```typescript
+// lib/sdk.ts
+import { HeadlessSDK, Environment } from '@arroact/umbraco-graphql-sdk';
+
+export const sdk = new HeadlessSDK({
+  environment: process.env.NEXT_PUBLIC_ENV as Environment,
+  graphqlUrl: process.env.GRAPHQL_URL!,
+  apiKey: process.env.GRAPHQL_API_KEY,
+  enableLogging: process.env.NEXT_PUBLIC_ENV === 'development',
+});
+
+// app/[slug]/page.tsx
+import { sdk } from '@/lib/sdk';
+
+export default async function Page({ params }: { params: { slug: string } }) {
+  const page = await sdk.getPageBySlug(params.slug);
+  
+  return (
+    <div>
+      <h1>{page?.title}</h1>
+      <div dangerouslySetInnerHTML={{ __html: page?.content || '' }} />
+    </div>
+  );
+}
+```
+
+## 📖 API Reference
+
+### `HeadlessSDK`
+
+Main SDK class for interacting with Umbraco GraphQL.
+
+#### Constructor Options
+
+```typescript
+interface SdkConfig {
+  environment: 'development' | 'staging' | 'production';
+  graphqlUrl: string;
+  apiKey?: string;
+  rootContentId?: string;
+  enableLogging?: boolean;
+  enableCache?: boolean;
+}
+```
+
+#### Methods
+
+##### `getPageBySlug(slug: string): Promise<PageModel | null>`
+
+Fetches a page by its URL slug.
+
+**Returns:**
+
+```typescript
+interface PageModel {
+  id: string;
+  slug: string;
+  title: string;
+  content: string;
+  metaTitle?: string;
+  metaDescription?: string;
+  publishedDate?: string;
+  updatedDate?: string;
+}
+```
+
+## 🏗️ Architecture
+
+The SDK is organized into clean, maintainable layers:
+
+```
+src/
+├── client/          # GraphQL client factory
+├── types/           # TypeScript type definitions
+├── queries/         # GraphQL queries
+├── models/          # Data models
+├── mappers/         # Data transformation
+├── services/        # Business logic
+├── core/            # Main SDK class
+└── index.ts         # Public exports
+```
+
+## 🔒 Environment Behavior
+
+### Development
+- Full logging enabled
+- Detailed error messages
+- Debug information
+
+### Staging
+- Partial logging
+- Error tracking
+- Performance monitoring
+
+### Production
+- Minimal logging (unless `enableLogging: true`)
+- Error suppression
+- Optimized performance
+
+## 🛠️ Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the SDK
+npm run build
+
+# Watch mode
+npm run dev
+
+# Type checking
+npm run lint
+```
+
+## 📦 Build Output
+
+The SDK builds to multiple formats:
+
+- `dist/index.js` - CommonJS
+- `dist/index.mjs` - ES Modules
+- `dist/index.d.ts` - TypeScript definitions
+
+## 🧩 Extending the SDK
+
+### Adding Custom Queries
+
+```typescript
+// queries/custom.query.ts
+import { gql } from 'graphql-request';
+
+export const GET_CUSTOM_DATA = gql`
+  query GetCustomData($id: ID!) {
+    content(id: $id) {
+      # your fields
+    }
+  }
+`;
+```
+
+### Adding Custom Services
+
+```typescript
+// services/custom.service.ts
+import { GraphQLClient } from 'graphql-request';
+
+export class CustomService {
+  constructor(private client: GraphQLClient) {}
+  
+  async getCustomData(id: string) {
+    // implementation
+  }
+}
+```
+
+## 📄 License
+
+MIT
+
+## 🤝 Contributing
+
+Contributions are welcome! Please maintain the existing code structure and style.
+
+## 📞 Support
+
+For issues and questions, please open a GitHub issue.

package/dist/index.d.mts

@@ -0,0 +1,181 @@
+import { GraphQLClient } from 'graphql-request';
+
+type Environment = 'development' | 'staging' | 'production';
+
+interface SdkConfig {
+    environment: Environment;
+    graphqlUrl: string;
+    mediaUrl?: string;
+    apiKey?: string;
+    rootContentId?: string;
+    enableLogging?: boolean;
+    enableCache?: boolean;
+}
+
+interface PropertyMetadata {
+    key: string;
+    dataType: string;
+    value: any;
+}
+declare class PageModel {
+    id: string;
+    name: string;
+    slug: string;
+    title: string;
+    content: string;
+    contentType: string;
+    url: string;
+    parentId?: string;
+    metaTitle?: string;
+    metaDescription?: string;
+    publishedDate?: string;
+    updatedDate?: string;
+    properties: Record<string, PropertyMetadata>;
+    children: PageModel[];
+    [key: string]: any | undefined;
+    constructor(data: {
+        id: string;
+        name: string;
+        slug: string;
+        title: string;
+        content: string;
+        contentType: string;
+        url: string;
+        parentId?: string;
+        metaTitle?: string;
+        metaDescription?: string;
+        publishedDate?: string;
+        updatedDate?: string;
+        properties: Record<string, PropertyMetadata>;
+        children?: PageModel[];
+    });
+    Value(propertyAlias: string): any;
+    HasProperty(propertyAlias: string): boolean;
+    getMediaUrl(propertyAlias: string): string;
+    toJSON(): any;
+    static hydrate(data: any): PageModel | null;
+}
+
+interface WhereInput {
+    propertyKey?: string;
+    propertyValue?: string;
+}
+interface OrderByPropertyInput {
+    propertyKey?: string;
+    direction?: 'ASC' | 'DESC';
+}
+interface QueryOptions {
+    first?: number | null;
+    skip?: number | null;
+    where?: WhereInput | null;
+    orderBy?: 'ASC' | 'DESC' | null;
+    orderByProperty?: OrderByPropertyInput | null;
+}
+
+declare class HeadlessSDK {
+    private client;
+    private pageService;
+    private rootContentId?;
+    private static mediaBaseUrl;
+    constructor(config: SdkConfig);
+    static getMediaBaseUrl(): string;
+    getPageBySlug(slug: string): Promise<PageModel | null>;
+    getContentById(id: string): Promise<PageModel | null>;
+    getRoot(): Promise<PageModel | null>;
+    getRootChildren(options?: QueryOptions): Promise<PageModel[]>;
+    getChildrenById(id: string, options?: QueryOptions): Promise<PageModel[]>;
+    getPageBySlugWithOptions(slug: string, options?: QueryOptions): Promise<{
+        page: PageModel | null;
+        children: PageModel[];
+    }>;
+    getMediaUrl(path: string): string;
+    static hydrate(data: any): PageModel | null;
+}
+
+declare function createGraphQLClient(config: SdkConfig): GraphQLClient;
+
+declare class PageService {
+    private client;
+    constructor(client: GraphQLClient);
+    getPageBySlug(slug: string): Promise<PageModel | null>;
+    getContentById(id: string): Promise<PageModel | null>;
+    getRootChildren(rootId: string, options?: QueryOptions): Promise<PageModel[]>;
+    getPageBySlugWithOptions(slug: string, options?: QueryOptions): Promise<{
+        page: PageModel | null;
+        children: PageModel[];
+    }>;
+}
+
+interface GraphQLProperty {
+    key: string;
+    value: string;
+    dataType: string;
+}
+interface GraphQLPageData {
+    id: string;
+    name: string;
+    contentType: string;
+    url: string;
+    properties: GraphQLProperty[];
+    createDate?: string;
+    updateDate?: string;
+    parentId?: string | null;
+}
+declare function mapGraphQLToPageModel(data: GraphQLPageData): PageModel;
+
+declare const GET_PAGE_BY_SLUG: string;
+
+declare const GET_CONTENT_BY_ID: string;
+
+declare const GET_ROOT_CHILDREN: string;
+declare const GET_PAGE_BY_SLUG_WITH_OPTIONS: string;
+
+interface BlockGridArea {
+    alias: string;
+    rowSpan: number;
+    columnSpan: number;
+    items: BlockGridItem[];
+}
+interface BlockGridItem {
+    contentType: string;
+    content: any;
+    settings?: any;
+    areas?: BlockGridArea[];
+    rowSpan?: number;
+    columnSpan?: number;
+    areaGridColumns?: number;
+}
+interface BlockGridData {
+    items?: BlockGridItem[];
+    blocks?: BlockGridItem[];
+}
+declare class BlockGridUtils {
+    static extractBlocks(blockGridData: any): BlockGridItem[];
+    static getComponentName(contentType: string): string;
+    static validateBlock(block: any): block is BlockGridItem;
+    static parseBlockGridData(data: any): {
+        blocks: BlockGridItem[];
+        errors: string[];
+    };
+}
+
+declare class BlockModel {
+    private _content;
+    private _settings;
+    private _contentType;
+    private _properties;
+    constructor(content: any, settings?: any, contentType?: string);
+    private parseProperties;
+    get content(): any;
+    get settings(): any;
+    get contentType(): string;
+    get properties(): Record<string, any>;
+    Value(propertyAlias: string): any;
+    Setting(propertyAlias: string): any;
+    HasValue(propertyAlias: string): boolean;
+    HasSetting(propertyAlias: string): boolean;
+    getMediaUrl(propertyAlias: string): string;
+}
+declare function createBlockModel(content: any, settings?: any, contentType?: string): BlockModel & Record<string, any>;
+
+export { type BlockGridArea, type BlockGridData, type BlockGridItem, BlockGridUtils, BlockModel, type Environment, GET_CONTENT_BY_ID, GET_PAGE_BY_SLUG, GET_PAGE_BY_SLUG_WITH_OPTIONS, GET_ROOT_CHILDREN, HeadlessSDK, type OrderByPropertyInput, PageModel, PageService, type PropertyMetadata, type QueryOptions, type SdkConfig, type WhereInput, createBlockModel, createGraphQLClient, mapGraphQLToPageModel };

package/dist/index.d.ts

@@ -0,0 +1,181 @@
+import { GraphQLClient } from 'graphql-request';
+
+type Environment = 'development' | 'staging' | 'production';
+
+interface SdkConfig {
+    environment: Environment;
+    graphqlUrl: string;
+    mediaUrl?: string;
+    apiKey?: string;
+    rootContentId?: string;
+    enableLogging?: boolean;
+    enableCache?: boolean;
+}
+
+interface PropertyMetadata {
+    key: string;
+    dataType: string;
+    value: any;
+}
+declare class PageModel {
+    id: string;
+    name: string;
+    slug: string;
+    title: string;
+    content: string;
+    contentType: string;
+    url: string;
+    parentId?: string;
+    metaTitle?: string;
+    metaDescription?: string;
+    publishedDate?: string;
+    updatedDate?: string;
+    properties: Record<string, PropertyMetadata>;
+    children: PageModel[];
+    [key: string]: any | undefined;
+    constructor(data: {
+        id: string;
+        name: string;
+        slug: string;
+        title: string;
+        content: string;
+        contentType: string;
+        url: string;
+        parentId?: string;
+        metaTitle?: string;
+        metaDescription?: string;
+        publishedDate?: string;
+        updatedDate?: string;
+        properties: Record<string, PropertyMetadata>;
+        children?: PageModel[];
+    });
+    Value(propertyAlias: string): any;
+    HasProperty(propertyAlias: string): boolean;
+    getMediaUrl(propertyAlias: string): string;
+    toJSON(): any;
+    static hydrate(data: any): PageModel | null;
+}
+
+interface WhereInput {
+    propertyKey?: string;
+    propertyValue?: string;
+}
+interface OrderByPropertyInput {
+    propertyKey?: string;
+    direction?: 'ASC' | 'DESC';
+}
+interface QueryOptions {
+    first?: number | null;
+    skip?: number | null;
+    where?: WhereInput | null;
+    orderBy?: 'ASC' | 'DESC' | null;
+    orderByProperty?: OrderByPropertyInput | null;
+}
+
+declare class HeadlessSDK {
+    private client;
+    private pageService;
+    private rootContentId?;
+    private static mediaBaseUrl;
+    constructor(config: SdkConfig);
+    static getMediaBaseUrl(): string;
+    getPageBySlug(slug: string): Promise<PageModel | null>;
+    getContentById(id: string): Promise<PageModel | null>;
+    getRoot(): Promise<PageModel | null>;
+    getRootChildren(options?: QueryOptions): Promise<PageModel[]>;
+    getChildrenById(id: string, options?: QueryOptions): Promise<PageModel[]>;
+    getPageBySlugWithOptions(slug: string, options?: QueryOptions): Promise<{
+        page: PageModel | null;
+        children: PageModel[];
+    }>;
+    getMediaUrl(path: string): string;
+    static hydrate(data: any): PageModel | null;
+}
+
+declare function createGraphQLClient(config: SdkConfig): GraphQLClient;
+
+declare class PageService {
+    private client;
+    constructor(client: GraphQLClient);
+    getPageBySlug(slug: string): Promise<PageModel | null>;
+    getContentById(id: string): Promise<PageModel | null>;
+    getRootChildren(rootId: string, options?: QueryOptions): Promise<PageModel[]>;
+    getPageBySlugWithOptions(slug: string, options?: QueryOptions): Promise<{
+        page: PageModel | null;
+        children: PageModel[];
+    }>;
+}
+
+interface GraphQLProperty {
+    key: string;
+    value: string;
+    dataType: string;
+}
+interface GraphQLPageData {
+    id: string;
+    name: string;
+    contentType: string;
+    url: string;
+    properties: GraphQLProperty[];
+    createDate?: string;
+    updateDate?: string;
+    parentId?: string | null;
+}
+declare function mapGraphQLToPageModel(data: GraphQLPageData): PageModel;
+
+declare const GET_PAGE_BY_SLUG: string;
+
+declare const GET_CONTENT_BY_ID: string;
+
+declare const GET_ROOT_CHILDREN: string;
+declare const GET_PAGE_BY_SLUG_WITH_OPTIONS: string;
+
+interface BlockGridArea {
+    alias: string;
+    rowSpan: number;
+    columnSpan: number;
+    items: BlockGridItem[];
+}
+interface BlockGridItem {
+    contentType: string;
+    content: any;
+    settings?: any;
+    areas?: BlockGridArea[];
+    rowSpan?: number;
+    columnSpan?: number;
+    areaGridColumns?: number;
+}
+interface BlockGridData {
+    items?: BlockGridItem[];
+    blocks?: BlockGridItem[];
+}
+declare class BlockGridUtils {
+    static extractBlocks(blockGridData: any): BlockGridItem[];
+    static getComponentName(contentType: string): string;
+    static validateBlock(block: any): block is BlockGridItem;
+    static parseBlockGridData(data: any): {
+        blocks: BlockGridItem[];
+        errors: string[];
+    };
+}
+
+declare class BlockModel {
+    private _content;
+    private _settings;
+    private _contentType;
+    private _properties;
+    constructor(content: any, settings?: any, contentType?: string);
+    private parseProperties;
+    get content(): any;
+    get settings(): any;
+    get contentType(): string;
+    get properties(): Record<string, any>;
+    Value(propertyAlias: string): any;
+    Setting(propertyAlias: string): any;
+    HasValue(propertyAlias: string): boolean;
+    HasSetting(propertyAlias: string): boolean;
+    getMediaUrl(propertyAlias: string): string;
+}
+declare function createBlockModel(content: any, settings?: any, contentType?: string): BlockModel & Record<string, any>;
+
+export { type BlockGridArea, type BlockGridData, type BlockGridItem, BlockGridUtils, BlockModel, type Environment, GET_CONTENT_BY_ID, GET_PAGE_BY_SLUG, GET_PAGE_BY_SLUG_WITH_OPTIONS, GET_ROOT_CHILDREN, HeadlessSDK, type OrderByPropertyInput, PageModel, PageService, type PropertyMetadata, type QueryOptions, type SdkConfig, type WhereInput, createBlockModel, createGraphQLClient, mapGraphQLToPageModel };