@tekrom/tsoft-app-gate 0.3.0 → 0.5.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/README.md +40 -5
- package/dist/client.d.ts +17 -1
- package/dist/client.js +10 -0
- package/dist/index.d.ts +1 -1
- package/dist/protocol.d.ts +17 -0
- package/dist/tsoft-app-gate.min.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -9,13 +9,13 @@ npm install @tekrom/tsoft-app-gate
|
|
|
9
9
|
Paketleyici kullanmıyorsanız tarayıcı derlemesini `<script>` ile yükleyin; aynı API `TSoftAppGate` global'i altında gelir:
|
|
10
10
|
|
|
11
11
|
```html
|
|
12
|
-
<script src="https://cdn.jsdelivr.net/npm/@tekrom/tsoft-app-gate@0.
|
|
12
|
+
<script src="https://cdn.jsdelivr.net/npm/@tekrom/tsoft-app-gate@0.4/dist/tsoft-app-gate.min.js"></script>
|
|
13
13
|
<script>
|
|
14
14
|
const app = TSoftAppGate.createApp();
|
|
15
15
|
</script>
|
|
16
16
|
```
|
|
17
17
|
|
|
18
|
-
Sürümü sabitleyin (`@0.
|
|
18
|
+
Sürümü sabitleyin (`@0.4` ya da tam sürüm); üretimde dosyayı kendi sunucunuzdan sunmak da mümkündür.
|
|
19
19
|
|
|
20
20
|
## Hızlı başlangıç
|
|
21
21
|
|
|
@@ -50,6 +50,11 @@ try {
|
|
|
50
50
|
|
|
51
51
|
await app.navigate.panel('order', 1042);
|
|
52
52
|
|
|
53
|
+
await app.nav.set([
|
|
54
|
+
{ label: 'Gönderiler', path: '/shipments' },
|
|
55
|
+
{ label: 'Ayarlar', path: '/settings' },
|
|
56
|
+
]);
|
|
57
|
+
|
|
53
58
|
const stop = app.autoResize();
|
|
54
59
|
```
|
|
55
60
|
|
|
@@ -118,6 +123,34 @@ Panelde başka bir sayfaya geçer (uygulama kapanır).
|
|
|
118
123
|
|
|
119
124
|
Kimlik `^[A-Za-z0-9_-]{1,64}$` kalıbına uymalı; bilinmeyen kaynak ya da geçersiz kimlik `invalid_route` döner.
|
|
120
125
|
|
|
126
|
+
### `nav.set(items)`
|
|
127
|
+
|
|
128
|
+
Panelin sol menüsünde (ve mobil menüde) uygulamanın adının altında alt menü gösterir; Shopify App Bridge'deki `ui-nav-menu` karşılığıdır. `items`: `{ label, path }` listesi.
|
|
129
|
+
|
|
130
|
+
- En fazla 8 öğe; `label` boş olamaz, en fazla 40 karakter.
|
|
131
|
+
- `path` uygulamanın kendi adresi altında, `/` ile başlayan yol olmalı (`/orders?status=1` gibi). Mutlak ya da başka origin'e giden adres, `//` ile başlayan yol ve `javascript:` reddedilir. `app_url` bir alt dizindeyse (`https://x.com/app/`) yol o dizinin altında kalmalı.
|
|
132
|
+
- Tek bir geçersiz öğe bütün listeyi `invalid_payload` ile reddeder; menü değişmez.
|
|
133
|
+
- Boş liste (`[]`) menüyü kaldırır.
|
|
134
|
+
|
|
135
|
+
Bağlantıya tıklanınca panel `?path=` değerini değiştirir ve iframe'i o yolla, yeni oturum token'ıyla yeniden yükler. Etkin bağlantı iframe'in o anki yoluna göre işaretlenir: önce bire bir eşleşme, sonra en uzun yol öneki (`/orders` bağlantısı `/orders/42` yolunda da etkin; `/` yalnız kendisiyle eşleşir). Uygulama kendi içinde gezindikçe `navigate.app` çağırırsa vurgu da güncel kalır.
|
|
136
|
+
|
|
137
|
+
Panel son gönderilen listeyi uygulama başına tarayıcıda saklar; menü bir sonraki açılışta uygulama yüklenmeden görünür. Alt menü uygulama panelde açıkken ya da menüye sabitlenmişken görünür. Listeyi her açılışta göndermeniz yeterlidir:
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
await app.nav.set([{ label: 'Gönderiler', path: '/shipments' }, { label: 'Ayarlar', path: '/settings' }]);
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### `modal.close({ refresh? })`
|
|
144
|
+
|
|
145
|
+
Uygulama bir **modal aksiyondan** (`[[extensions]]` hedefi `admin.{order,product,customer}.detail.action`) açıldıysa modalı kapatır. `refresh: true` panelin o sayfanın verisini (sipariş, ürün, müşteri) yeniden yüklemesini ister; örneğin uygulama siparişe fatura yazdıysa. Uygulama tam sayfada (`/apps/open`) açıldıysa `unsupported_type` döner.
|
|
146
|
+
|
|
147
|
+
Modalda `navigate.app` panel adresini değiştirmez; `navigate.panel` modalı kapatıp panelde o sayfaya gider. Diğer bütün çağrılar tam sayfadaki gibi çalışır.
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
await saveInvoice();
|
|
151
|
+
await app.modal.close({ refresh: true });
|
|
152
|
+
```
|
|
153
|
+
|
|
121
154
|
### `pickResource({ type, multiple? })`
|
|
122
155
|
|
|
123
156
|
Panelin seçicisini açar, seçilen kayıtların kimliklerini döner: `{ ids, cancelled }`. Kullanıcı pencereyi kapatırsa `{ ids: [], cancelled: true }`. Varsayılan olarak zaman aşımı yoktur.
|
|
@@ -148,7 +181,7 @@ Tüm reddedilen promise'ler `AppBridgeError` taşır; `code` alanı aşağıdaki
|
|
|
148
181
|
|
|
149
182
|
| Kod | Kaynak | Anlamı |
|
|
150
183
|
|---|---|---|
|
|
151
|
-
| `invalid_payload` | panel | Zorunlu alan boş ya da tipi yanl
|
|
184
|
+
| `invalid_payload` | panel | Zorunlu alan boş ya da tipi yanlış; `nav.set` listesinde geçersiz öğe. |
|
|
152
185
|
| `invalid_path` | panel | `navigate.app` yolu geçersiz ya da uygulama origin'i dışında. |
|
|
153
186
|
| `invalid_route` | panel | `navigate.panel` kaynağı bilinmiyor ya da kimlik geçersiz. |
|
|
154
187
|
| `missing_scope` | panel | Uygulamanın bu iş için gereken kapsamı yok. |
|
|
@@ -169,7 +202,7 @@ Panel uygulamanın `app_url` adresini (yalnız `https`, panel origin'inden farkl
|
|
|
169
202
|
|
|
170
203
|
- `session`: Oturum JWT'si.
|
|
171
204
|
- `code`: Yalnız kurulumdan hemen sonraki ilk açılışta, kurulum kodu.
|
|
172
|
-
- Panel URL'inde `?path=/x` varsa uygulama `app_url` origin'i altındaki `/x` yolundan açılır.
|
|
205
|
+
- Panel URL'inde `?path=/x` varsa uygulama `app_url` origin'i altındaki `/x` yolundan açılır. `?path=` panel tarafında değişirse (alt menü bağlantısı) iframe o yolla yeniden yüklenir; `navigate.app`'in yazdığı yol yeniden yükleme yapmaz.
|
|
173
206
|
|
|
174
207
|
iframe `sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads"`, `allow="clipboard-write"` ve `referrerpolicy="strict-origin"` ile açılır. Üst pencereye yönlendirme (`allow-top-navigation`) yoktur; panelde gezinmek için `navigate.panel` kullanılır.
|
|
175
208
|
|
|
@@ -206,6 +239,8 @@ Kurallar:
|
|
|
206
239
|
| `navigate.panel` | `{ resource, id? }` | `{}` | `invalid_route` |
|
|
207
240
|
| `resource.pick` | `{ type, multiple? }` | `{ ids, cancelled? }` | `unsupported_resource`, `missing_scope` |
|
|
208
241
|
| `size.set` | `{ height }` | `{}` | `invalid_payload` |
|
|
242
|
+
| `nav.set` | `{ items: [{ label, path }] }` | `{}` | `invalid_payload` |
|
|
243
|
+
| `modal.close` | `{ refresh? }` | `{}` | `unsupported_type` (tam sayfada) |
|
|
209
244
|
| diğer | — | — | `unsupported_type` |
|
|
210
245
|
|
|
211
246
|
`confirm.open` ve `resource.pick` yanıtı kullanıcı işlem yapınca gelir.
|
|
@@ -241,7 +276,7 @@ Script panel dışında açılınca ilk istekte hata veriyordu; `createApp()` is
|
|
|
241
276
|
|
|
242
277
|
### 0.1.x'ten
|
|
243
278
|
|
|
244
|
-
0.1.x'teki `createApp({ apiKey, shopId, host })`, `setNavigationMenu` ve `showToast` panelin tanımadığı bir mesaj biçimi (`T_SOFT_APP_BRIDGE`) gönderiyordu; kaldırıldı. `showToast(app, opts)` yerine `app.toast(message, opts)` kullanın;
|
|
279
|
+
0.1.x'teki `createApp({ apiKey, shopId, host })`, `setNavigationMenu` ve `showToast` panelin tanımadığı bir mesaj biçimi (`T_SOFT_APP_BRIDGE`) gönderiyordu; kaldırıldı. `showToast(app, opts)` yerine `app.toast(message, opts)` kullanın; `setNavigationMenu` yerine 0.4.0'dan beri `app.nav.set(items)` var.
|
|
245
280
|
|
|
246
281
|
## Geliştirme
|
|
247
282
|
|
package/dist/client.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type BridgeErrorCode, type PanelDetailResource, type PanelListResource, type PickableResource, type RequestPayloads, type RequestType, type ResponsePayloads, type ToastVariant } from './protocol.js';
|
|
1
|
+
import { type BridgeErrorCode, type NavItem, type PanelDetailResource, type PanelListResource, type PickableResource, type RequestPayloads, type RequestType, type ResponsePayloads, type ToastVariant } from './protocol.js';
|
|
2
2
|
export declare class AppBridgeError extends Error {
|
|
3
3
|
readonly code: BridgeErrorCode;
|
|
4
4
|
constructor(code: BridgeErrorCode, message?: string);
|
|
@@ -82,6 +82,22 @@ export interface App {
|
|
|
82
82
|
panel(resource: PanelListResource, options?: RequestOptions): Promise<void>;
|
|
83
83
|
panel(resource: PanelDetailResource, id: string | number, options?: RequestOptions): Promise<void>;
|
|
84
84
|
};
|
|
85
|
+
nav: {
|
|
86
|
+
/**
|
|
87
|
+
* Panelin sol menüsünde uygulamanın altındaki bağlantıları ayarlar (en fazla 8).
|
|
88
|
+
* Tıklanan bağlantı iframe'i o yolla yeniden yükler; panel listeyi tarayıcıda saklar.
|
|
89
|
+
*/
|
|
90
|
+
set(items: NavItem[], options?: RequestOptions): Promise<void>;
|
|
91
|
+
};
|
|
92
|
+
modal: {
|
|
93
|
+
/**
|
|
94
|
+
* Uygulama bir modal aksiyondan (`[[extensions]]` `.detail.action`) açıldıysa modalı kapatır.
|
|
95
|
+
* `refresh: true` panelin o sayfanın verisini yeniden yüklemesini ister. Tam sayfada açılmışsa `unsupported_type`.
|
|
96
|
+
*/
|
|
97
|
+
close(options?: {
|
|
98
|
+
refresh?: boolean;
|
|
99
|
+
} & RequestOptions): Promise<void>;
|
|
100
|
+
};
|
|
85
101
|
/** Panelin seçicisini açar. Varsayılan olarak zaman aşımı yoktur. */
|
|
86
102
|
pickResource(options: PickOptions): Promise<PickResult>;
|
|
87
103
|
/** iframe yüksekliğini ayarlar; panel 300–5000 px aralığına sıkıştırır. */
|
package/dist/client.js
CHANGED
|
@@ -160,6 +160,16 @@ export function createApp(options = {}) {
|
|
|
160
160
|
return empty('navigate.panel', { resource }, idOrOptions);
|
|
161
161
|
},
|
|
162
162
|
},
|
|
163
|
+
nav: {
|
|
164
|
+
set(items, requestOptions) {
|
|
165
|
+
return empty('nav.set', { items: items.map(({ label, path }) => ({ label, path })) }, requestOptions);
|
|
166
|
+
},
|
|
167
|
+
},
|
|
168
|
+
modal: {
|
|
169
|
+
close({ refresh, ...requestOptions } = {}) {
|
|
170
|
+
return empty('modal.close', { refresh: refresh === true }, requestOptions);
|
|
171
|
+
},
|
|
172
|
+
},
|
|
163
173
|
async pickResource({ type, multiple, ...rest }) {
|
|
164
174
|
const response = await request('resource.pick', { type, multiple: multiple === true }, rest, 0);
|
|
165
175
|
return { ids: Array.isArray(response.ids) ? response.ids : [], cancelled: response.cancelled === true };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
export { createApp, isEmbedded, decodeSessionToken, AppBridgeError, PANEL_ORIGIN_PATTERN } from './client.js';
|
|
2
2
|
export type { App, AppOptions, AutoResizeOptions, ConfirmOptions, PickOptions, PickResult, RequestOptions, SessionClaims, SessionToken, ToastOptions, } from './client.js';
|
|
3
3
|
export { BRIDGE_VERSION, APP_SOURCE, PANEL_SOURCE } from './protocol.js';
|
|
4
|
-
export type { BridgeErrorCode, BridgeRequest, BridgeResponse, PanelDetailResource, PanelListResource, PanelResource, PickableResource, RequestPayloads, RequestType, ResponsePayloads, ToastVariant, } from './protocol.js';
|
|
4
|
+
export type { BridgeErrorCode, BridgeRequest, BridgeResponse, NavItem, PanelDetailResource, PanelListResource, PanelResource, PickableResource, RequestPayloads, RequestType, ResponsePayloads, ToastVariant, } from './protocol.js';
|
package/dist/protocol.d.ts
CHANGED
|
@@ -32,6 +32,15 @@ export type PanelDetailResource = 'order' | 'product';
|
|
|
32
32
|
export type PanelResource = PanelListResource | PanelDetailResource;
|
|
33
33
|
/** Seçici türü ve istediği kapsam: `product` → `read_products`. */
|
|
34
34
|
export type PickableResource = 'product';
|
|
35
|
+
/**
|
|
36
|
+
* Panelin sol menüsünde uygulamanın adı altında görünen bağlantı. `path` uygulamanın
|
|
37
|
+
* kendi adresi altında `/` ile başlayan yol olmalı (`/orders?status=1` gibi); etiket
|
|
38
|
+
* en fazla 40 karakter. Liste en fazla 8 öğe; boş liste menüyü kaldırır.
|
|
39
|
+
*/
|
|
40
|
+
export interface NavItem {
|
|
41
|
+
label: string;
|
|
42
|
+
path: string;
|
|
43
|
+
}
|
|
35
44
|
export interface RequestPayloads {
|
|
36
45
|
'session-token.get': Record<string, never>;
|
|
37
46
|
'toast.show': {
|
|
@@ -57,6 +66,12 @@ export interface RequestPayloads {
|
|
|
57
66
|
'size.set': {
|
|
58
67
|
height: number;
|
|
59
68
|
};
|
|
69
|
+
'nav.set': {
|
|
70
|
+
items: NavItem[];
|
|
71
|
+
};
|
|
72
|
+
'modal.close': {
|
|
73
|
+
refresh?: boolean;
|
|
74
|
+
};
|
|
60
75
|
}
|
|
61
76
|
export interface ResponsePayloads {
|
|
62
77
|
'session-token.get': {
|
|
@@ -75,6 +90,8 @@ export interface ResponsePayloads {
|
|
|
75
90
|
cancelled?: boolean;
|
|
76
91
|
};
|
|
77
92
|
'size.set': Record<string, never>;
|
|
93
|
+
'nav.set': Record<string, never>;
|
|
94
|
+
'modal.close': Record<string, never>;
|
|
78
95
|
}
|
|
79
96
|
export type RequestType = keyof RequestPayloads;
|
|
80
97
|
/**
|
|
@@ -1 +1 @@
|
|
|
1
|
-
"use strict";var TSoftAppGate=(()=>{var
|
|
1
|
+
"use strict";var TSoftAppGate=(()=>{var E=Object.defineProperty;var L=Object.getOwnPropertyDescriptor;var D=Object.getOwnPropertyNames;var U=Object.prototype.hasOwnProperty;var z=(n,o)=>{for(var i in o)E(n,i,{get:o[i],enumerable:!0})},V=(n,o,i,d)=>{if(o&&typeof o=="object"||typeof o=="function")for(let a of D(o))!U.call(n,a)&&a!==i&&E(n,a,{get:()=>o[a],enumerable:!(d=L(o,a))||d.enumerable});return n};var G=n=>V(E({},"__esModule",{value:!0}),n);var H={};z(H,{APP_SOURCE:()=>T,AppBridgeError:()=>p,BRIDGE_VERSION:()=>P,PANEL_ORIGIN_PATTERN:()=>b,PANEL_SOURCE:()=>O,createApp:()=>B,decodeSessionToken:()=>v,isEmbedded:()=>S});var P=1,T="tsoft-app",O="tsoft-panel";var p=class extends Error{constructor(o,i){super(i!=null?i:`T-Soft App Bridge: ${o}`),this.name="AppBridgeError",this.code=o}},M=1e4,F=15e3,b=/^https:\/\/([a-z0-9-]+\.)*(tsoftpanel\.com|tsoftpanel\.net|paneltsoft\.com)$/;function S(){return typeof window!="undefined"&&window.parent!==window}function j(){let n=window.location.ancestorOrigins;if(n&&n.length>0)return n[0];try{return document.referrer?new URL(document.referrer).origin:null}catch(o){return null}}function v(n){try{let o=atob(n.split(".")[1].replace(/-/g,"+").replace(/_/g,"/")),i=JSON.parse(new TextDecoder().decode(Uint8Array.from(o,d=>d.charCodeAt(0))));return i&&typeof i.exp=="number"?i:null}catch(o){return null}}function $(n){return n!==null&&n.expiresAt-F>Date.now()}function B(n={}){var q,_;if(!S())throw new p("not_embedded","T-Soft App Bridge: uygulama panel iframe'i i\xE7inde a\xE7\u0131lmam\u0131\u015F");let o=n.panelOrigin?null:j();if(!n.panelOrigin&&!(o&&b.test(o)))throw new p("not_embedded",`T-Soft App Bridge: \xFCst pencere bir T-Soft paneli de\u011Fil (${o!=null?o:"bilinmiyor"})`);let i=(q=n.panelOrigin)!=null?q:o,d=(_=n.timeout)!=null?_:M,a=new Map,k=new URLSearchParams(window.location.search),x=k.get("session"),I=0,A=!1,l=null,R=null;if(x){let t=v(x);t&&(l={token:x,claims:t,expiresAt:t.exp*1e3,scopes:null})}function w(t){var r;if(t.source!==window.parent||t.origin!==i)return;let e=t.data;if((e==null?void 0:e.source)!==O||(e==null?void 0:e.version)!==1||typeof(e==null?void 0:e.id)!="string")return;let s=a.get(e.id);s&&(a.delete(e.id),clearTimeout(s.timer),e.ok===!0?s.resolve((r=e.payload)!=null?r:{}):s.reject(new p(typeof e.error=="string"?e.error:"internal_error")))}window.addEventListener("message",w);function m(t,e,s={},r=d){var f;if(A)return Promise.reject(new p("destroyed"));let u=`app-${Date.now().toString(36)}-${(I++).toString(36)}`,g=(f=s.timeout)!=null?f:r;return new Promise((y,C)=>{let N={resolve:y,reject:C};g>0&&(N.timer=setTimeout(()=>{a.delete(u),C(new p("timeout"))},g)),a.set(u,N),window.parent.postMessage({source:T,version:1,id:u,type:t,payload:e},i)})}async function h(t={}){return!t.forceRefresh&&$(l)?l:(R!=null||(R=m("session-token.get",{},t).then(e=>(l={token:e.token,claims:v(e.token),expiresAt:Date.now()+e.expires_in*1e3,scopes:Array.isArray(e.scopes)?e.scopes:[]},l)).finally(()=>{R=null})),R)}async function c(t,e,s){await m(t,e,s)}return{panelOrigin:i,get claims(){var t;return(t=l==null?void 0:l.claims)!=null?t:null},installCode:k.get("code"),getSession:h,async getSessionToken(t){return(await h(t)).token},toast(t,{variant:e,...s}={}){return c("toast.show",e?{message:t,variant:e}:{message:t},s)},async confirm(t){let{message:e,title:s,confirmText:r,...u}=typeof t=="string"?{message:t}:t;return(await m("confirm.open",{message:e,title:s,confirmText:r},u,0)).confirmed===!0},navigate:{app(t,e){return c("navigate.app",{path:t},e)},panel(t,e,s){return typeof e=="string"||typeof e=="number"?c("navigate.panel",{resource:t,id:String(e)},s):c("navigate.panel",{resource:t},e)}},nav:{set(t,e){return c("nav.set",{items:t.map(({label:s,path:r})=>({label:s,path:r}))},e)}},modal:{close({refresh:t,...e}={}){return c("modal.close",{refresh:t===!0},e)}},async pickResource({type:t,multiple:e,...s}){let r=await m("resource.pick",{type:t,multiple:e===!0},s,0);return{ids:Array.isArray(r.ids)?r.ids:[],cancelled:r.cancelled===!0}},setHeight(t,e){return c("size.set",{height:Math.ceil(t)},e)},autoResize({target:t}={}){let e=t!=null?t:document.body,s=0,r=0,u=()=>{r=0;let f=getComputedStyle(e),y=Math.ceil(e.getBoundingClientRect().height+parseFloat(f.marginTop)+parseFloat(f.marginBottom));y!==s&&(s=y,m("size.set",{height:y}).catch(()=>{}))},g=new ResizeObserver(()=>{r||(r=requestAnimationFrame(u))});return g.observe(e),()=>{g.disconnect(),r&&cancelAnimationFrame(r)}},request:m,destroy(){A=!0,window.removeEventListener("message",w);for(let t of a.values())clearTimeout(t.timer),t.reject(new p("destroyed"));a.clear()}}}return G(H);})();
|